he 
E 


- SystemTask; 
Dolt: = GetNextEvent( 
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Ask Prof. Mac 


Readers Technical Questions 


SCSI 


Q. Its widely rumored that Apple is going to offer an 
upgrade that includes a "SCSI port." What's that? 

A. Atthis writing Apple has made no announcements about 
such an upgrade, but assuming that the rumors are true let's 
talk about SCSI. This is just a background briefing -- if the 
Mac does get a SCSI connection, the only programmers who 
will need to be concerned with its details are those who write 
device driver and other low-level software to talk to the SCSI 
devices that attach to the Mac. 

SCSI stands for Small Computer Systems Interface and 
is usually pronounced as "scuzzy." It is a standard 8-bit-wide 
data bus that is increasingly popular in the industry for 
connecting peripheral devices to each other and to host 
computers. 

SCSI is an enhancement and standardization of SASI 
(Shugart Associates Systems Interface), a disk controller 
interface which was originated by Shugart, the disk drive 
manufacturer, in the late '70s and widely used. SASI was 
submitted to ANSI (American National Standards Institute) for 
official standardization. In the process its name was changed 
to drop the association with a particular vendor, and protocols 
were added to enable multiple hosts to coexist on the bus, to 
allow peripherals to release the bus during their execution of 
long processes and then reconnect with the host which issued 
the command, and to add commands oriented to devices other 
than disks (e.g., tape drives). 

The basic purpose of SCSI, like that of other buses 
(S100, VME, Qbus, Multibus, etc.) is to connect devices 
whose manufacturers may never have heard of one another so 


SCSI host 


adapter 


Steve Brecher 
Software Supply 
MacTutor Contributing Editor 


that the devices can send data back and forth in a coordinated 
way. SCSI specifies both the electrical aspects of the 
connection and a communication protocol. Up to 8 devices 
(peripheral controllers and/or computers) can be connected toa 
SCSI bus. 

The bus consists of 8 data lines ("wires"), one data parity 
line, and 9 control signal lines. (For reasons best known to 
the hardware folks, a 50-line cable is usually used for SCSI 
interconnections.) Data transfer is asynchronous -- that means 
that an explicit control signal handshake protocol is used to 
coordinate the transfer of each byte (as opposed to 
synchronous, which means that the communicating devices 
use a common clock signal to pace data transfers). 

The maximum SCSI data transfer rate is more than 
1MByte/sec -- thus fast peripherals will have to wait for the 
Mac rather than vice-versa. The Mac, lacking DMA (Direct 
Memory Access) cannot transfer more than about 
0.5Mbyte/sec into and out of RAM, because each byte 
transferred (recall that SCSI is an 8-bit-wide data bus) requires 
at least one CPU instruction and two 68000 bus accessess - 
- data source and destination -- in addition to the access for the 
instruction fetch. That's not counting any additional 
instructions such as for loop control. 

A typical SCSI bus system is shown in Figure 1. This 
is a single-host system -- only one computer -- which allows 
the computer to drive the peripherals connected to the bus. 
The illustration shows only two peripherals, but there could 
be up to 7 (the host is one of the up to 8 devices that can 
attach to the bus). 

The host adapter in the computer interfaces between the 
SCSI bus and the CPU. CPUs like the 68000 which use 
memory-mapped I/O would communicate with the host adapter 


Figure 1 
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by writing to or reading from fixed addresses -- just as the Mac 
communicates with its serial and diskette hardware at fixed 
addresses. 

The bus allows any one pair of devices connected to it to 
be in communication at a given time. One of the devices 
(usually the computer) is the Initiator and the other (usually a 
peripheral) is the Target. The Initiator obtains use of the bus, 
and selects a Target; the Target responds to indicate it is 
selected, and then the two devices have exclusive use of the 
bus until they release it The Initiator sends commands to the 
Target, and the Target executes them. The set of possible 
commands includes Read (send data to me), Write (take the 
following data), Format (a disk), Rewind (a tape drive), etc. 

SCSI peripheral controllers are fairly intelligent. For 
example, to read from a disk device, the Initiator (computer) 
need specify only a logical block address (a relative data block 
offset) and the number of blocks. The target controller then 
translates this into a low-level disk location (cylinder, head, 
sector). Historically, driver software in the computer has been 
responsible for such translation to low-level terms, because 
that's all that "dumb" disk controllers were able to understand. 
In addition to making things simpler for the host computer 
device driver software, this kind of controller intelligence 
allows a higher degree of device-independence -- the same way 
that a high-level programming language allows CPU- 
independence. 

| Soft Coding 

Q. "ELL" on Delphi notes that Apple often warns against 
"hard-coding" constants such as screen and memory sizes into 
programs, but some example programs from Apple seem to 
include such constants nonetheless. 

Á. Do as they say, not as they do. Any program that's 
going to be used more than once (or farther into the future 
than five minutes) should be defensively programmed to 
assume that anything about its environment that might 
change, will change. Even today a program might be run on 
machines varying in memory size from 128K to 2MB, and 
varying in screen size from the Mac's screen to the XL's. 

Handling an arbitrary screen size can be difficult with 
respect to multiple windows which contain many elements and 
which have been designed to look pretty. But that's no excuse 
for avaoiding simple measures, such as calculating at run time 
instead of hard-coding the positions of a window which should 
be centered. 

To get the lazy started, I've provided in Figure 2 a couple 
of routines to vertically and horizontally center a rectangle. 
The code is trivial, but it illustrates the use of a couple of 
macros discussed in the next question. 

In those cases in which constants must be used, they 
should be defined mnemonically (e.g., using EQU in 
assembler or Const in Pascal) That makes them easy to 
identify and change. 

Macros 
Q. I havent seen many macros used in the assembly 
programs I've looked at. Could you give some examples of 
macro usage? 
A. I have a file of macro definitions that I incorporate 
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into most programs using the MDS Asm Include facility. 
The file is shown in Figure 3. 

The first set of macros compensates for an MDS bug 
which generates incorrect results for some comparison 
operators. For example, instead of 

If A<B 
which doesn't work properly, I use the macro .LT.: 

If A .LT. B 
(I stole the substance of these comparison macros from the 
TMON user area source code.) 

The second and most elaborate set of macros is used to 
avoid errors in stack addressing for a routine's arguments, 
result, and temporaries. Figure 4 shows an example of how 
this set of macros is used. 

The Assume macro is useful for explicitly stating 
assumptions made by the code (usually relating to the value of 
an offset which is defined in an Equ file, or to the adjacency of 
values accessed with autoincrement or autodecrement 
addressing). For example, the code in Figure 2 contains: 

Assume top=0 
Add (A0),DO 

Coding top(AO) wastes a word if top=0; including the 
Assume macro in this case makes clear what is going on (as 
well as protecting the program from undetected error should 
the offset of "top" ever change). 

The various Push and Pop macros reduce the amount of 
typing required to code pushes and pops of the A7 stack as 
well as making the program easier to read (at least to my eye). 

The BitDefinitions and Bit macros make it easy to 
define mnemonic values for bit numbers and masks which are 
used with flag bytes and hardware registers. Coding 

BitDefinitions InterruptFlags 


Bit OneSec 
Bit VertBlank 
Bit KbdRdy 
;etc. 
is the equivalent of coding 
OneSecBit Equ 0 
OneSecMask Equ 1 
VertBlankBit Equ 1 
VertBlankMask  Equ2 
KbdRdyBit Equ 2 
KbdRdyMask Equ4 
;etc. 
spExtra 


Q. Bill Bynum of Williamsburg, VA noticed that both 
Inside Macintosh and the June '85 issue of MacTutor (p. 45) 
indicate that the spExtra field of a grafPort record is a word, 
while in the MDS file QuickEqu.Txt, it's shown as a long 
(Pascal data type "fixed") There is a corresponding 
discrepancy in the total size of a grafPort. 

A. When in doubt, always go by the Equ files -- they're used 
by the folks at Apple who write systems software. 

SpExtra is 4 bytes long, and a grafPort is 108 bytes 
long. Theoretically spExtra is of "fixed" data type, i.e., a 32- 
bit value with an implicit binary point in the middle. This 
implies that that spaces can be extended by a fractional number 


3 


of pixels. However, in the current ROM QuickDraw 
effectively uses only the high-order word of spExtra. That's 
why the SpaceExtra trap works with an integer argument as 
it's documented in JM . QuickDraw moves a long argument 
from the stack to the field in the grafPort. Since the caller 
pushed only a word argument, the low-order word of the 
spExtra field in the grafPort will be whatever word happened 
to be above the caller's word argument on the stack. But since 
the low-order word doesn't really affect QuickDraw's 
calculations, all is well. 
Figure 2 Source Code 


Include QuickEqu.D 
Include Macros jsee Figure 3 
MBarHt Equ 20 ,vertical size of menu bar 


procedure VertCenterRect(VAR myRect: rect) 


Adjust the top and bottom of the rect so that the rect is 
vertically centered in the desktop area for current 
Screen size. 


Wwe We "e We We We DW 


StackFrame NotLinked 


Arg myRect,Long 
J 
VertCenterRect: 

Move.L (A52,A0 ,addr of QuickDraw globals 

Move screenBitstboundstbottomC(Ad), D8 
,vertical size of screen 

Move.L myRect(SP), Ad ,addr of caller's rect 

Move bottomCAd),D1 ;D1 = bottom of caller's rect 

Sub D1,D2 ;DØ = old bottom margin 

Assume top=8 ; (macro) 

Add CAG), DB ;* old top margin, DØ = total 
;vertical margin 

Lsr #1,00 ;DØ = 1/2 of the vert space 
snot used by rect 

Add t MbarHt/2,D0 ,adjust for menubar, DØ = 
,hew top of rect 

Sub CAG), D1 ;D1 = vertical size of rect 

Move DO, CAD) jset new top 

Add D1,D0 ,hew bottom = top + size 

Move DO, bottom Ad) ,set new bottom 

Return ; (macro) 


procedure HorzCenterRect(VAR myRect: rect) 


Adjust the left and right of the rect so that the rect is 
horizontally centered for current screen size. 


Wwe "e We We We We 


StackFrame NotLinked 
Arg myRect, Long 


HorzCenterRect: 
Move.L 
Move 


CA5), AO ;addr of QuickDraw globals 
screenBitstboundstr ightCA2),D0 
;DØ = horz size of screen 


Move.L myRect(SP), Ad ,addr of caller's rect 

Move rightCA2)2,D1 ;01 = right of caller's rect 

Lea lef t CA02, AQ ;,point to left coordinate 
,of rect 

Sub D 1,D0 ;U9 = old right margin 

Add CAO), DB ,* old left margin, DØ = 
; total horz margin 

Lsr 81,D0 ¿DØ = 1/2 of the horz space 
;hot used by rect 

Sub (A02,D1 ;01 = horizontal size of rect 

Move DO, CAD) ,set new left 

Add D1,D0 ,new right = left + size 

Move DO,right-leftCA0) ;set new right 

Return ; (macro) 

4 


Figure 3 


; Macros.Asm -- General purpose MDS macros 


f Macros to work around MDS Asm comparison reversal bug 


If 10 


Else 


Endif 


Macro 
Macro 
Macro 
Macro 


Macro 
Macro 
Macro 
Macro 


LT. 
LE. 


Vv VA ^ 
it 


jif bug is present 


nn — 


jif bug is not present 


; Subroutine stack frame definition macros 


J 
; Usage: 


4 


StackFrame Linked 


j «or? 


s 


, 
, 
, 
j 
i 
; 
j 
4 
a 
4 
j 
) 
, 
, 
, 
, 
j 


StackFrame «anything else? 


Arg 
Arg 


caller 


ArgN, ArgNLen 


Arg1,ArgiLen 


Resul tResul tName, Resul tLen 
Local 1,Local iLen 


Local 


Local 


‘Routine: 


Link 


Return 


Notes: 


StackFrame is required. 


LocalN,LocalNLen 


A6, #-LocalsSize 


jif A6 link to be used 
jif no A6 link to be used 
; last arg pushed by caller 


;first arg pushed by 


;if StackFrame Linked 


Each of the other types of 
, macro invocations is optional, but if present their 
relative ordering must be as shown. 


f Arguments (Arg macro invocations) must appear in 


the reverse of the order in which the caller pushes 
the arguments. 


ResultLen is ignored, but provided for documentary 


4 
) 
P 
P 
P 
; purposes. 


Macro StackFrame Type = 
If ‘{Type}' = ‘Linked’ 


.RtnAddr. . Set 4 
. ArgOffs.. Set 8 
Else 
. RtnAddr. . Set ø 
. .ArgOffs.. Set 4 
Endif 
. .ArgsSz.. Set ø 
LocalsSize Set Ø 
Macro Arg Name,Len = 
(Name) Set . .Argoffs.. 
. .ArgOffs.. Set 
| . Argssz.. Set 
Macro Result Name,Len = 
(Name) Set . ArgOffs.. 
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(Name) * (Len) *C (Len) & 1) 
. ArgOffs..-. .RtnAddr. .-4 


Macro Local Name,Len = 
(Name) Set Q-LocalsSize- (Len) -C (Len)& 1) 
| LocalsSize Set 0- (Name) 
Macro Return = 
If ..RtnAddr.. =4 
Unik A6 
Endif 
If ..ArgsSz.. 69 
Move.L CSP D+, Ad ,return addr 
If ..ArgsSz.. .LE. 8 
AddQ *..ArgsSz..,$9P 
Else 
Lea . ArgsSz. . (SP2,SP 
Endif 
Jmp (AQ) 
Else 
Rts 


f Def ine standard lengths 
, 

Byte Equ ! ,Same affect as Word 

; use for declarative purpose 
Word Equ 2 

Long Equ 4 


Macros to push and pop stack 


) 
Macro Pop.B Dest = 
If ‘(Dest} ' O ti 
Move.B (SP)+, (Dest) 
Else 
Tst.B CSP + 


~ 


jpop and set condition codes 
jper Boolean 


Macro Pop Dest = 
If ' (Dest) ' 0 '' 
Move.W  CSP2*, (Dest) 
Else 
AddQ #2,SP 
d 


Macro Pop.L Dest = 
If {Dest} ' 0o '' 
Move.L (SP)+, (Dest) 
Else 
AddQ #4,SP 
m 


Macro Push.B Src = 
Move.B (Src},-C(SP) 


Macro Push Src = 
Move.W (Src},-CSP) 


Macro Push.L Src = 
Move.L {Src},-CSP) 


Macro PushM Regs = 
MoveM.W {Regs} ,-C(SP) 


Macro PushM.L Regs = 
MoveM.L (Regs) ,-(SP) 
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Macro PopM Regs = 
MoveM.W (SP)+, (Regs) 


Macro PopM.L Regs = 
MoveM.L (SP)+, (Regs) 


; Macro to make an assertion about an assumed condition 


Macro Assume Cond = 
If (Cond) 
Else 
Assumption error -- (Cond) 
dd 


; Macros to decare bits and masks 
; Usage 
; BitDefinitions ID 


setup -- ID is documentary only 
; Bit Namel 
P 


;Defines Name ibit=8, Name Imask= 1 
Bit NameN 


;Def ines NameNbit=N, 
NameNmask= 1««N 


Macro —— BitDefinitions ID 


! .BitNbr. Set Ø 
Macro Bit Name = 
(Name)bit Equ  .BitNbr. 
(Name) mask Equ = i««(Name)bit 
,BitNbr. Set — (Name)bit*1 
Figure 4 


Include SysEqu.D 
Include  MacTraps.D 
Include Macros 


s 

; Function CanGetInfoCvRefNum, DirID: integer; FileNamePtr: 
Ptr): boolean 

; Calls .HGetFileInfo (HFS version) if DirID«d, 

; otherwise _GetFilelnfo. 

; Returns true if the trep result is noErr. 


é 
ioHFQElSize Equ $6C ;size of HFS parameter 
block 
ioDirID Equ $30 ;offset of DirID 
) 
StackFrame Linked 
Arg FileNamePtr, long 
Arg DirID,word 
Arg vRefNum, word 
Result Flag,byte 
Local ioPB, ioHFQE1Size 
4 
CanGetInfo: 
Link A6, ®-LocalsSize 
Lea ioPBCA6), A0 ,addr of parameter block 


Move.L Fi leNamePtrCA6), ioFileNemeCAQ) 
Move vRef NumCA62, ioVRef NumCAQ) 
Cir.B ioFVersNumCA2) ,version number always 0 


Cir ioFDirIndexCA2) jnot an indexed call 
Move DirIDCA62,D0 ,HFS? 
Bne.S eo j yes 
-GetFileInfo jno 
Bra.$ e1 
eü0 Move DØ, ioDirIDCAQ) 
-HGetF i leInfo 
61 Assume noErrzQ 
Seq FlagCA6) ,set result 
Return 


Assembly Lab 


Icon Converter Shows Disk I/O 


In the second issue of MacTutor, David Smith presented 
a program that I valued as one of my most useful utilities - 
- the Icon Converter. This program would take an icon 
generated by Apple's Icon Editor and convert it to an MDS 
compatable text file, making it far easier to create icon 
resources for assembly programs. However, the Icon 
Converter didn't give a catalog of files , didn't display the 
icons on the screen, and worse of all, was written in MS 
Basic. This most likely presented little trouble to the 
majority of users, but due to the chaotic organization of my 
disks, I found it frustrating. 


This month's column covers the design of an assembly 
language Icon Converter application that includes these 
features. As well as developing a valuable utility, the 
column will explain some of the programming techniques 
involved in disk I/O using SFGetFile in such an application. 
The reader is invited to review my "Micro-Finder" utility in 
MacTutor, Vol. 1 No. 7 which covered an introduction to 
the standard file package from assembly. Remember, programs 
which follow the strict Apple guidelines will work with the 
new standard file package under Finder 5.0. So as not to be 
redundant, I will assume that the reader understands the basic 
concepts of assembly language programming covered in 
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previous issues. 
Nature of Bit Maps 

First, we must recognize that an icon fits into the 
general category of BitMap. A BitMap is a QuickDraw data 
structure that represents a rectangular arrangement of bits. The 
bits themselves define an image simply by representing 
whether the corresponding pixel is on or off. The structure of 
a BitMap is that of a record with three fields. The PASCAL 
TYPE definition is as follows: 


TYPE BitMap = RECORD 
baseAddr : QDPtr; 
rowBytes : INTEGER; 
bounds : Rect 
END; 


The first field is baseAddr, a pointer to the actual bit 
image in memory. The next field is rowBytes, an integer that 
tells how wide (in bytes) each row of the image is. The last 
field is bounds; it is a rectangle describing the usable area of 
the bit image. This allows the programmer to define BitMaps 
which have widths that do not lie on byte boundaries. A 
sample BitMap is shown in Figure #1; however, realize that 
this is not an Icon BitMap. Whereas an Icon BitMap is 32 by 


Icon Converter 3.0 
©1985 by Chris Yerga for MacTutor 


Icon 


Mask 


columns 2... 


32 pixels, the sample BitMap is only 8 by 8 pixels. 


sample Bitmap 


00011000 
00100100 
01000010 
10000001 


I— 8 Pixels —3 
Figure 1 


Now, given the information that an icon is always 32 by 
32 bits in size, we can see that the rowBytes and bounds 
fields of all icon BitMaps are the same. To calculate 
rowBytes, we take the number of bits, or pixels, 
horizontally and divide by 8 to determine how many bytes are 
needed to hold them. 8 divides evenly into 32 to give us a 
rowBytes value of 4. The bounds rectangle needed to enclose 
the 32 by 32 bits of the icon is simply 0,0,32,32. So the 
only data in an icon's BitMap that changes is the actual bit 
image of the icon. 


It follows that in order to store an icon on a disk, the bit 
image is the only data that needs to be written. Examining 
files produced by Apple's old icon editor clearly shows that 
this is the scheme they used. The net result is that it is 
extremely easy to make use of files saved in this format. 


File Manager Reviewed 


In order for a program to access data stored in a file on 
disk, it must use the File Manager. The File Manager | 
employs a register based calling scheme to pass parameters 
between itself and the calling program. 
mentioned in previous installments, address register AO 
points to a data structure in memory upon entry to a register 
based routine - IOParamBlock is used in this case. The 
proper fields of the IOParamBlock are filled with data, AO is 
loaded, and then the desired trap is called. A digram showing 
which IOParamBlock fields are appropriate for the various File 
Manager calls is included in figure #2. 


Before any data can be read from or written to a file, the 
file must be opened. This allows the File Manager to locate 
the file and create an access path to the file. In order for the 
file to be opened, the program must allocate 522 bytes of 
memory for the access path buffer and pass it to the Open 
routine. After the file is opened, a path reference number, 
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. GetFPos 
. SetFPos 


. SetEOF 
. Allocate 


As has been — 


not to be confused with a volume reference number, is 
returned. This reference number is then used to refer to the file 
in following File Manager calls. 
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_Write 


Passed to trap 
=| Received from trap 
= Both Passed & Received 


Figure #2 


The program will go about reading an icon file in the 
following manner. First, the SFGetFile package will be 
called to get the filename of the file to be loaded. Ironically, 
Apple's Icon Editor breaks with their own standards in that it 
doesn't assign a filetype or creator to the files it creates. It 
leaves these fields cleared! Our program tells the SFGetFile 
package to list all files with NIL values for filetype and 
creator. As it turns out, Icon Editor files are usually the only 
ones that fit this criterion, but occasionally some strange file 
will find its way into the SFGetFile list. (Anyone unfamiliar 
with the workings of the SFGetFile package should read 
MacTutor Vol 1 #7, where I covered the Standard FIle 
package in more detail than is appropriate here.) 


Once the desired file is known, it must be opened. 
Figure 2 shows us which parameters must be passed. 
IOCompletion will be NIL, because we don't want the File 
Manager to call a routine after it is done; rather, we want it 
to return control to us. The filename, refnum, and version 
number are given to us by the SFGetFile call, and are passed 
unchanged. The value 1 is stored in the IOPermission field to 
specify read-only access to the file. Finally, a pointer to the 
access path buffer is passed. The _Open trap is called and 
assuming no errors were flagged, the file is now ready to be 
read. 

Reading Disk Files 


Once the file is opened, the program is free to read the 
data from it. The File Manager stores the data it reads in the 
memory block pointed to by the ioBuffer field of the 
ioParamBlock. Since the BasAddr field of an icon's BitMap 
points to its bit image, which is what we want to load, we 
set ioBuffer equal to BasAddr. ReqCount tells the File 
Manager how many bytes to read from the file. Multiplying 
the BitMap's rowBytes value (4) by its number of rows 
vertically (32) gives the value 128 for this field. The 
ioPosMode and ioPosOffset fields are both cleared, because 
the special positioning features of the File Manager are not 
needed in this case. The Read trap is then invoked. The 
input operation is now finished, and the . Close trap is called. 


Icon Displayed via CopyBits 


It is helpful to see the icons on the screen after they have 
been loaded. This is achieved through the CopyBits procedure, 
which can be used to transfer a BitMap to the screen. Its 
PASCAL interface follows: 


PROCEDURE CopyBits 
(srcBits,dstBis: BitMap; srcRect, 
dstRect: Rect; mode: INTEGER; 
maskRgn: RgnHandle); 


The first parameter passed to CopyBits is a pointer to the 


source BitMap, which is our icon BitMap. This is followed 
by a pointer to the destination BitMap. The destination 
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BitMap will be that of the current GrafPort, which is stored 
beginning at 2 bytes past the beginning of the GrafPort data. 
After this is pushed, we push srcRect, which describes the 
rectangular region of the source BitMap to be copied. The 
entire BitMap is to be copied, of course, so 0,0,32,32 is 
sent. dstRect is next, and for it we pass a 32 by 32 rectangle 
describing where on the screen we want the icon displayed. 
The next word of data determines which transfer mode is used. 
Zero is used to set the standard copy mode. The last parameter 
is a handle to a region to which the BitMap should be masked, 
and is useless in this instance. NIL is passed. _CopyBits is 
then called and the icon is displayed inside DestRect. 


Now that the icon is loaded and displayed, it's binary bit 
image must be converted to ASCII data for the MDS file. The 
program allocates 2K of memory to house the ASCII data 
before it is written to the destination file. The conversion 
process is a simple loop that stores "DC.B" at the beginning 
of each line, converts 8 bytes of hex data to ASCII, stores 
this ASCII data, stores a carriage return for the end of the 
line, and loops. The main part of the this loop is the hex to 
decimal conversion routine, HexToAscii, which takes a hex 
byte in DO and converts it to an ASCII word which is returned 
in D1. It's code is straightforward and commented, and I 
recommend examining it, as the functional value of the 
program is based on it. 


The final step of the conversion process is writing the 
MDS file out to disk. First, we must call the SFPutFile trap 
to get the desired filename from the user. Next, the file must 
be created on the volume, a task handled by the File 
Manager's _Create trap (appropriately enough...). As usual, 
ioCompletion is NIL. The file name and volume reference 
number, which specifies the volume that will contain the new 
file, are given to us by the SFPutFile. Finally, we must 
specify a 1 byte version number for the file. As we are 
unconcerned with version numbers, this field will contain 
NIL. After this is done, we call the _Create trap and continue 
with the next step. 


As in reading, we must first open the destination file 
before we can perform any I/O. Since we have just set the 
ioCompletion, ioNamePtr, ioVRefNum, and ioVersNum 
fields, we do not need to do so again. The value 1 is stored in 
the IOPermission field to specify read-only access to the file. 
À pointer to the 522 byte access path buffer is passed, and the 
file is Opened. 


Writing to Disk Files 


Now we are ready to do the actual writing. The first step 
is to calculate the length of the ASCII data in our 2K buffer. 
This is necessary because the actual data will not fill the entire 
buffer. After this value has been found, it is stored in the 
ioReqCount field, informing the File Manager of how much 
data needs to be written. Next, the base address of the buffer 
is stored in ioBuffer. Finally, ioPosMode and ioPosOffset are 
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cleared to disable these features of the File Manager, and the 
_Write trap is called. 


Setting Type and Creator Bytes 
We now have an file of ASCII data on the disk, but we 


need to give it filetype and creator tags in order for MDS to 
recognize it. The filetype will be TEXT, and the creator will 


be EDIT. The trap that allows us to set these stamps is 


_SetFileInfo. Unfortunately, however,  SetFileInfo also 
sets about a dozen other pieces of file information, and 
requires that they be specified as well. The solution is to first 
call _GetFileInfo, which reads the current information fields 
from the file and stores them in the ioParamBlock. In 
essence, we are letting  GetFileInfo do the tedious business 
of passing the other parameters to  SetFileInfo. So we call 
_GetFileInfo, set the filetype and creator, and then call 
_SetFileInfo. 


We are now finished writing the file, so we _Close it. 
The final step is to call _FlushVol to insure that everything 
gets updated on the volume. 


Chris Yerga wins $50 for the outstanding program 

of the month with this feature article. Congratulations! 
a eee EE MED 

It is quite possible that an IO error will occur during one 
of the above operations. In such an event, the File Manager 
returns an error code in ioResult. A copy of this error code is 
also placed in DO. After every I/O operation, the program 
invokes a macro which checks D0 for an error code. If one is 
found, it displays a dialog box alerting the user of an error and 
aborts to the main menu. 


Dialog Box Makes it User Friendly 


The above steps are the heart of the conversion section of 
the program. The external features, such as the appearance of 
the program and so on are fairly simple, involving a single 
dialog box to support the features described above. Menus 
have been omitted not to save us from writing extra code, but 
rather to create a more efficient interface. It is my belief that 
menus are useful only in applications involving several 
possible categories of actions that the user may take (ie: 
Filing commands, Editing commands, Font commands, 
etc). In such an application, menus serve to organize the 
possible choices and thus make them more manageable to the 
user. Whereas in our case, the application serves but one 
purpose, and consequently, all the possible actions the user 
may take fall under one category. 


I hope that this article and the source code will help 
explain the basic workings of the File Manager. If not, 
perhaps the program itself will be useful. If even that is of no 
use to you, then perhaps you shouldn't have read this far. [But 
if you did, you've learned a lot! Thanks Chris for a great 
column. -Ed.] 
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P 
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NCLUDE 


Icon Converter 3.9 
€ Copyright 1985 by Chris Yerga 


for MacTutor 


MacTreps.D 


; Declare external labels 


XDEF 
. TRAP _MakeF 


START 


ile $4008 ;The -Create trap 
¿which is not in 


¿the MDS trap f ile 


; * Define Macros e 


MACRO IsError = 
CMP. W #9 DØ ;Check for nonzero DØ 
BEQ @2 
BRA ioErr ;pop up the error dialog 
82: 
| 
MACRO Center String,MidPT,Y = 


CLR.W -(SP) ;Save room for INTEGER 
width of string 
PEA ' (String)' 
-StringWidth 
CLR.L D3 ;Clear the high word of D3 
,So0 the DIVU works 
MOVE .W (SP)*,D3;Get the width Cin pixels) 
jin D3 
DIVU #2,D3 Divide by 2 
MOVE.L 1t (MidPT},D4 
SUB. W D3,D4 ;Subtract CWidth/2) from 
; 103 to center text 
MOVE .W D4,-(SP) ;Push the X coordinate 
MOVE.W "(Y),-CSP) ;Push the Y coordinate 
-MoveTo ,Position the pen 
PEA — '(String)' 
-DrawS 


tring 
| jEnd of Macro 


,* Local Constants € 


AllEvents 
MaxEvents 
DWindLen 


EQU — $0000FFFF ; Mask for FlushEvents 
EQU 12 
EQU $44 ; The size of a Dialog 


;Record 


,* Start of Main Program e 


BadPtr: 
-Debugger ;Should never get here. Is called 
;when there is a problem with the 
memory manager. 
Io£rr: 
CLR.L -(SP) ;Save room for DIalogPtr 
MOVE.W 8 159,-CSP) ;The ResID of the error dialog 
PEA ErrDialogCA5) ,Where to put the DialogRec 
MOVE.L 8-],-CSP) ,Put it in front, please... 
-GetNewDialog 
LEA ErrDHandle, A2 ,Save handle, but keep it 
MOVE.L (SP), CA2) jon the stack 
-DrewDialog ;Draw the dialog.. 
LEA ErrDHandle, A2 
MOVE.L (A22, -CSP) ,Set the Dialog to the current 
-SetPort ;erafPort 
Center Sorry! That operation was 
interrupted, 152,20 

Center by an I/0 error. Check the disk 
and, 150,32 

Center try again., 150,44 

BSR AwaitOK 


MOVE.L 


ErrDHandle,-(SP)  ;Get rid of the dialog 


-DisposDialog 
MOVE.L MainPort,-CSP) ,restore the main port 
-SetPort jas the active port 
BRA Main ,abort to the main menu 
START : 
MOVEM.L D0-D7 /A0-A6, -CSP) 

; The standard-issue routine 
LEA SAVEREGS, Ad ¿which saves the registers 
MOVE.L A6, CAG) 
MOVE.L AT, 4CAB) 


;* Initialize the ROM routines € 


PEA -4(A5) ;,Q0 Global ptr 

-InitGraf jInit QD global 
_InitFonts jInit font manager 
-InitWindows ; Init Window Manager 
-InitMenus ;Guess what...you got it! 
CLR.L -(SP) ;Standard SysErr/DS dialog 
-InitDialogs ;Init Dialog Manger 
-TEInit ;Init ROM Text edit 
MOVE.L 8AlT1Events,D2; And flush ALL previous 
-FlushEvents jevents 

-InitCursor ;CGet the standard arrow 
PEA GrayPat 

-BackPat 

PEA Screen ;Clear the screen 
-EreseRect 

PEA WhitePat 

-BackPat 


;* Allocate some Memory € 


MOVE.L *80 ,D0 ;Get 80 Bytes for IOParamBlock 
-NewPtr 

IsError ,Hendle any error 

LEA IOPeremBlock,A1 ;Save the Ptr 

MOVE.L A0,CA1) 

MOVE.L #522,D0 ,Get 522 Bytes for access 
-NewPtr ;peth buffer 

IsError ,Hendle any error 

LEA APBuffer,A1 ,Save the Ptr 

MOVE.L AQ, CA1) 

MOVE.L $* 128,D0 ;Get 128 Bytes for Icon Data 
-NewPtr 

IsError ;Do the error thing... 

LEA IconBitMap, A1 ,Save the Ptr 

MOVE.L Ad, CA1) 

MOVE.L #128,DØ ;Get 128 Bytes for Mask Data 
-NewPtr 

IsError ;Do the error thing... 

LEA MaskBi tMap, A1 jsave the Ptr 

MOVE.L A8,CA1) 

MOVE.L 452048, D0 ;Get 2K bytes for Target 
-NewPtr jfile buffer 

IsError 

LEA ConvertBuf , A1 ,save the ptr 

MOVE.L A0,CA1) 


,* Set up the Dialog Box € 


CLR.L -(SP) ;Seve room for DIalogPtr 

MOVE.W 8128, -CSP) ;The ResID of the dialog 

PEA MainDialogCA5 ) ,Where to put the DialogRec 

MOVE.L 8-1,-CSP) ;Put it in front, please... 

-GetNewDialog 

LEA MainDHandle, A2 ;Save handle, but keep it 

MOVE.L (SP), (A2) jon the stack 

-DrewDialog ;Draw the dialog.. 

LEA Ma inDHandle, A2 

MOVE.L CA2),-CSP) ,Set the Dialog to the _SetPort 
,current GrafPort 
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PEA IconFrame 


-FrameRect 


PEA MaskFrame 


-FrameRect 
MOVE .W 
_TextFont 
MOVE .W 
_TextSize 
Center 
MOVE .W 
_TextFont 
MOVE .W 
-lextSize 
Center 


CLR.W 
_TextFont 
PEA 
_GetPort 


Outline the ICON box 
;Ditto for the MASK 


#7,-(SP) ; Athens 

818,-CSP)  ;18 Pt 

Icon Converter 3.0,200,30 

82 ,-(SP) ; Geneva 

812,-CSP)  ;12 Pt 

©1985 by Chris Yerga for 

MacTutor, 208,45 

-CSP) ¿Chicago 

MainPort ;Save the GrafPtr for the Main port 


,* Main Event Loop € 


Main: 
CLR.L 
PEA 


_ModalDialog 


MOVE 
CMP .B 
BEQ 
CMP .B 
BEQ 
CMP .B 
BEQ 
CMP .B 
BEQ 
CMP .B 
BEQ 
CMP .B 
BEQ 
BRA 


Adios: 
LEA 
MOVE.L 
MOVE.L 
MOVEM.L 
RTS 


OpenIcon: 
BSR 
BEQ 
LEA 
BSR 
BSR 
BRA 


BSR 
BEQ 
LEA 
BSR 
BSR 
BRA 


StdMask : 
MOVE.L 
MOVE.L 
FillMask: 
MOVE.L 
DBRA 

BSR 

BRA 


Convert: 
MOVE.L 
MOVE.L 


-(SP) ,NIL for FilterProc 
ItemHit ,VAR ItemHit 
ItemHit ,D@ ;Get the Item # 
#1,D9 ;Open an Icon? 
OpenIcon 

82 DO ;Open a Mask? 
OpenMask 

83, DO ;Standard Mask? 
StdMask 

84 DO ;Do the conversion? 
Convert 

85, D0 jHelp? 

Help 

"6 DO Quit? 

Adios 

Main ; loop til we get a good event 
SaveRegs, Ad 

CAO), A6 

ACAD), AT 


(SP)*,D0-D7/A0-A6 


GetFile ;Get filename 

Main ,user hit «Cancel» 

IconBi tMap, A3 ,Set up params for read 
ReadIcon jread the file 

PlotIcon ;draw the icon 

Main 

GetFile j}Get filename 

Main ,user hit cancel 

MaskBi tMap, A3 ;set up for read... 
ReadIcon ;read the file 

PlotMask ,display the mask 

Main 

MaskB i tMap, Ad ;Get Ptr to Bitmap data 
831,D0 j; loop 32 times 
"$FFFFFFFF,CAQ)* — ;fill the mask with black 
D0,FillMask ; loop until we're done 
PlotMask 

Main 

Conver tBuf , A2 Fill the file buffer with 
IconBi tMap, A3 ; the icon definition 
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BSR IconToMDS on return: 
MOVE.W #$ØDØD, CA2)+ ;,Stick in a few cr's for F Di = ASCII word result 
,Spacing j uses DØ, D1,D4, AØ 
MOVE.L MaskB i tMap, A3 ; & the mask definition 
BSR IconToMDS HexToAsci1: 
BSR PutFile ;Get the filename for save MOVE .B D0,04 ;save copy of byte 
BEQ Main ,user cancelled out LSR #4 DØ ;Get the high nibble 
MOVE.L A2,D2 jsave the buffer Ptr ANDI H$OF ,DO ;mask out all extraneous bits 
MOVE.L T0ParamB lock , A2 ;Get Ptr in A2 LEA ByteTable,A® ;Get base address of table 
CLR.L 12(A2) ;,No completion routine MOVE.B (A0,D025,D1 ;Move Ist ascii byte into D1 
LEA GF i leName , AØ j; ioNamePtr ASL 88. D] ,move the byte to the proper position 
MOVE.L AO, 18CA2) ,save it in IOPB ANDI "$9F ,D4 ,get the low nibble 
MOVE.W GetVRef ,22(42) ,volume ref # MOVE .B CAB,D4),D8  ;Get 2nd ascii byte 
CLR.B 26(A2) ,version ® = f OR.W D,D! ,Store 2nd byte in word 
MOVE.L A2, A RTS 
-MakeF ile generate the file 
IsError ByteTable: 
DC.B 'Ø 123456789ABCDEF ' 
MOVE .B 82,21(A2) ;write-only permission 
MOVE.L APBuffer,28CA2) pointer to our access MOVE.L Help: 
A2,A0 ;path buffer CLR.L -(SP) ,Save room for DIalogPtr 
-Open ;open the data fork of the file MOVE.W 8129,-(SP)  ;The ResID of the help dialog 
IsError PEA HelpDialog(A5) ;Where to put the DialogRec 
MOVE.L 1-],-CSP) ;Put it in front, please... 
MOVE.L Conver tBuf ,D1 ;Get the Base address of _Ge tNewDialog 
; the buffer LEA He lpDHandle, A2 ;Save handle, but keep it 
SUB .L D1,D2 juse it to calculate the MOVE.L CSP), CA2) jon the stack 
j length of buffer -DrawDialog ;Draw the dialog.. 
MOVE.L ConvertBuf,32(A2) ;Buffer ptr LEA HelpDHandle, A2 
MOVE.L D2,36(A2) write the whole buffer MOVE.L (A2),-CSP)  ;Set the Dialog to the current 
CLR .W 44(42) ,Standard positioning -SetPort ;GrafPort 
CLR.L 46(A2) ;With no offset 
MOVE.L A2,A0 Center The Icon Converter is based on an 
write ¿write the buffer MS-Basic Program, 224,20 
IsError Center written by David Smith and presented in 
MacTutor Vol. 1 #2,224,32 
CLR.W 28(A2) jno directory index Center that takes a file generated by the Apple 
MOVE.L A2,A0 ;Get the current file info Icon Editor and, 224,44 
-GetF i leInfo So we don't have to set Center converts it to an MDS format TEXT type 
,everything file to save the,224,56 
MOVE.L 8'TEXT',32(A2) jfile type = TEXT Center programmer from the tedious task of 
MOVE.L 8'EDIT',36(A2) ;creator = EDIT typing in the HEX data,224,68 
MOVE.L A2, A write the info Center by hand. ,224, 80 
-SetF i leInfo Center This program is an adaptation of the 
original,224,97 
MOVE.L A2,A0 ;Close out the file Center Icon Converter in assembly 
- Close language. , 224, 109 
IsError BSR AwaitOK ,wait for the user to click OK 
MOVE.L A2,A0 ;& flush the volume PEA Screen ,clear the dialog box 
-FlushVol -EraseRect 
IsError MOVE.L HelpDHandle,-CSP) ¿Redraw the dialog 
BRA Main -DrawDialog 
IconToMDS: Center Clicking in either of the Open buttons 
MOVE.L 815,D2 ; loop 16 times (16 lines of code) allows the user t0,224,20 
NextRow Center open a file generated by the old icon editor 
MOVE.L #7,D3 ;put 8 bytes of data in each line for either, 224,32 
MOVE.L LineStart,(A2)+  ;Put the 'DC.B ' at the Center the icon or mask respectively. ,224, 44 
MOVE.B LineStart+4,CA2)+ beginning of each line Center Clicking in the None button tells the Icon 
@3: Editor/Conver ter , 224,61 
MOVE .B CA3)+, DØ ;Get next byte of data Center to generate a standard mask for the icon 
BSR HexToAsci i ,get ascii word in D1 Call black2.,224,73 
MOVE .B #'$',(A2)+ precede digit with $ for hex Center Clicking in the Convert button converts the 
MOVE .W D1, CA2)+ ,Store ascii equivalent of byte displayed icon,224, 98 
MOVE .B #',',(A2)+ ;store comma separator Center and mask to an MDS compatable 
DBRA D3, 63 ; loop till we've done 8 bytes file.,224, 102 
SUBA 81,A2 ,replace the last comma w/ cr BSR — AwaitOK ,wait for the user to click OK 
MOVE.W ®$200D, CA2)+ PEA Screen ¿Clear the dialog box 
DBRA D2,NextRow ,loop till we've done 16 lines -EraseRect 
RTS ,Of code MOVE.L HelpDHandle,-CSP) ;Redraw the dialog 
-DrawDialog 
| Center Subscribe to MacTutor - the no fluff 
, HexToAscii routine -> converts a hex byte to an Macintosh programming, 224,29 
P ASCII word Center journal - to learn how to write programs 
j on entry: like this in,224,32 
^ DØ = Hex byte to be converted Center Assembly Language on the Mac.,224,44 
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Center $30 per year will keep you on top of 
Macintosh programming, 224,61 


Center in Assembly Language/Basic/C/Forth/Pascal and 
many, 224, 73 

Center other langueges!,224,85 

Center MacTutor P.0. Box 400 Placentia Ca 
92670 ,224, 102 

Center or call (714) 638-3738 ,224, 119 

BSR AwaitoK 

MOVE.L HelpDHandle,-(SP) ;Get rid of the dialog 

-DisposDialog 

MOVE.L MainPort,-(CSP) restore the main port 

-SetPort jas the active port 

BRA Main 

AwaitOK: 

CLR.L -(SP) jNIL for FilterProc 


PEA ItemHit ,VAR ItemHit 
-ModalDialog 

MOVE ItemHit,D0 ;Get the Item # 

CMP .B #1,D2 jwas it OK? 

BNE AwaitOK 

RTS 

; ReadIcon routine: 

s 

on entry A3 contains a ptr to the bitmap which 
; will receive the data. 

ReadIcon: 

MOVE.L 10ParamB lock, A2 ;Get Ptr in A2 

CLR.L 12(42) ,No completion routine 
LEA GF i leName, Ad ; 1oNameP tr 

MOVE.L A0, 18CA2) jsave it in IOPB 

MOVE GetVRef ,22(42) ;the volume refNum 
MOVE.B GetVers,26(A2) ;the file version # 
MOVE.B 8$1,27(42) jread-only permission 
MOVE.L APBuffer,28CA2) . ;the access path buffer 
MOVE.L A2,A0 Ptr to IOPB 

-Open jOpen the file 
IsError jhandle any error 
MOVE.L (A32,32(A2) ,data buffer 

MOVE.L 8 128, 36(A2) ;* of bytes to read 
CLR .W 44(A2) ;Standerd positioning 
CLR.L 46(A2) ;no offset 

-Read ,read the data 

IsError jhope for no errors 

MOVE.L A2,A0 ;close the file 

-Close 

IsError 
. RTS 

GetFile: 

MOVE.W #82,-(SP) ;X Coordinate 

MOVE .W 8 187,-CSP) jy Coordinate 

PEA "PROMPT ' Prompt (Unused) 
MOVE.L 80,-(SP) ;NIL for ProcPtr 
MOVE.W#1,  -(SP) ;We only want 1 file type listed 
PEA TypeList ; The TypeList 

MOVE.L "9 -(SP) ;NIL for digHook 

PEA SFRep ly j The Reply Record 
MOVE.W 82,-(SP) ;Routine Selector for _Pack3 

;SFGetFile 

LEA SFReply, Ag ;check for successful call 
CMP .B 8D, CAD) 

RTS 

PutFile: 

MOVE.W * 104, -CSP) ;X coordinate 

MOVE.W 1198, -(SP) ;y coordinate 

PEA ‘Save MDS file es: ';Prompt 

PEA ‘Untitled. ICON’  ;Default name 

CLR.L -(SP) ;Standerd dialog box 
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PEA SFRep ly ; the reply record 

MOVE .W 81,-CSP) ;Routine selector for SFPutFile 
-Pack3 

LEA SFReply, A ;check for successful call 
CMP.B 80 (AQ) 

RTS 

PlotIcon: 

PEA  CurPort ;get the GrafPtr in CurPort 
-GetPort 

MOVE.L CurPort, Ag jput it in A8 

PEA  IconBitMap j Source 

PEA 2CA®) ,dest 


PEA SourceRect 
PEA IconRect 


¿Source rect 
jdest rect 


CLR.W -(SP) ;SrcCopy mode 
CLR.L -(SP) jno mask region 
-CopyB i ts 
RTS 
PlotMask : 
PEA CurPort ,get the GrafPtr in CurPort 
-GetPort 
MOVE.L CurPort , Ad ;put it in A0 
PEA — MaskBitMap j Source 
PEA  2(A0) ;dest 


PEA — SourceRect ;Source rect 


,dest rect 


R.W -(SP) ;,SrcCopy mode 
CLR.L -CSP) ;ho mask region 
-CopyBi ts 
RTS 


;* Program Variables è 


SaveRegs: DCB.L 2,0  ;For saving the SP etc.. 
MainDHandle:DC.L Ø ;For the main dialog 
,Hendle 


HelpDHandle:DC.L Ø 
ErrDHandle: DC.L Ø 


;For the Help dialog Handle 
;For the ioErr dialog 


Handle 
ItemHit: DC.W Ø ;For .ModalDialog 
10ParamBlock: DCL Ø 
APBuf fer: DCL Ø 


; * That's all....Enjoy! € 
Linker File 
ISTART 


/Output IconVert 
/Bundle 


] 
IconVert 


/Resources 
ResIcon 


/TYPE 'APPL' 'BDOGC' 


* IconVert 3.0 € 
by Chris Yerga for MacTutor 


RESOURCES 
i e 
RESOURCE ‘BDOG' Ø 
STRING.FORMAT 2 


DC.B 'IconVert 3.8 - Chris Yerga 8/4/85' 
STRING-FORMAT Ø 
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. ALIGN 2 

RESOURCE 'BNOL' 128 

DC.L ‘BDOG' jName of Signature 
DC.W 0,1 

DC.L 'FREF' ;FREF mappings 
DC.W Ø ;1 mapping (1-1 = Ø) 
DC.W 0, 128 
DC.L 'ICONt' ; ICN® mappings 
DC.W Ø ;1 mapping (1-1 = Ø) 
DC.W 0,128 

. ALIGN 2 


RESOURCE 'FREF' 128 
DC.B 'APPL',0,0,0 


„ALIGN 2 
RESOURCE 'ICN"' 128 
INCLUDE Martini. ICON 


"Application Icon' 
jput your icon here 


„ALIGN 2 


RESOURCE 'DLOG' 128 ‘Appl Dialog' 


DC.W 29,56, 178, 456 ;BoundsRect 

DC.W 1 ;Dialog Box w/ Outline 
DC.B 1,1 ,Visible 

DC.B 0,0 ;,NoCoAway 

DC.L 0 ;Refcon... 

DC.W 128 ;,UITL ResID 

DC.B 'BOX' ;litle CUnused) 

. ALIGN 2 


RESOURCE 'DLOG' 129 'Help Dialog' 


DC.W 175,32,330,480 ;BoundsRect 

DC.W 1 ;Dialog box w/ outline 
DC.B 1,1 ,Visible 

DC.B 0,0 jNoGoAway 

DC.L 0 ;Refcon... 

DC.W 129 ;DITL ResID 

DC.B 'HELP' ;Title (not used) 
„ALIGN 2 


RESOURCE 'DLOG' 158 'ioErr Dialog' 


DC.W 135, 106,205, 406 ;BoundsRect 

DC.W 1 ;Dialog box w/ outline 
DC.B 1,1 ,Visible 

DC.B 9,8 ;NoGoAway 

DC.L Ø ;Ref Con 

DC.W 150 ,UITL ResID 

DC.B 'ERR' jlitle 

. ALIGN 2 


RESOURCE 'DITL' 128 
STRING.FORMAT 2 


DC.W 7 ;8 Items (8-127) 

* Item #1 * 

DC.L 0 ¿Handle Holder 

DC.W 690,94, TT, 144 j Bounds 

DC.B 4 ;Button 

DC.B 'Open' iText w/ length byte 


© The Complete MacTutor, Vol. 2 


* [tem 82 * 

DC.L 0 

DC.W 60,256,77,306 
DC.B 4 

DC.B 'Open' 


* Item #3 * 

DC.L Ø 

DC.W 79,256,96, 306 
DC.B 4 


DC.B 'None' 


* [tem 84 * 

DC.L Ø 

DC.W 118,40, 137, 140 
DC.B 4 


DC.B 'Convert ' 


* Item #5 x 
DC.L Ø 

DC.W 118, 150, 137,250 
DC.B 4 

DC.B 'Help' 


x Item 56 * 

DC.L Ø 

DC.W 118,260, 137,360 
DC.B 4 


DC.B ‘Quit: 


* [tem 87 * 

DC.L Ø 

DC.W 98, 154,113, 190 
DC.B 136 

DC.B 'Icon' 


* [tem #8 * 

DC.L Ø 

DC.W 98,210,113,246 

DC.B 136 

DC.B 'Mask' 

.ALIGN 2 

RESOURCE 'DITL' 129 'Help I 
DC.W 0 


* [tem #1 * 

DC.L Ø 

DC.W 135, 199, 152,249 

DC.B 4 

DC.B 'OK' 

. ALIGN 2 

RESOURCE 'DITL' 150 'Err It 
DC.W Ø 


* [tem #1 * 

DC.L Ø 

DC.W 51, 120,68, 189 

DC.B 4 

DC.B 'Oh no!' 

STRING_FORMAT @ E 


Handle Holder 
; Bounds 
;Button 
;lext w/ length byte 


jHandle Holder 
;Bounds 
;Button 
jText w/ length byte 


,Handle Holder 


,Text w/ length byte 


,Hendle Holder 
j Bounds 
Button 
,Text w/ length byte 


Handle Holder 
; Bounds 
Button 
j Text w/ length byte 


;Handle Holder 
; Bounds 
;Button 
;Text w/ length byte 


;Handle Holder 
;Bounds 
¿Static text 
;Text w/ length byte 


tens ' 
;1 Item €1- 120) 


handle holder 
;BoundsRect 
;Button 

title 


ems ' 
31 Item C1-120) 


;handle holder 
;BoundsRect 

;Button 

title 

set things back to normal 


(ora ra E oN 
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Assembly Lab 
Launch Doc Utility in MacAsm 


Whew! This program, which started out being a simple 
little thing, got complicated in a hurry! 

Welcome to Launch Doc, the MacTutor document 
launching utility. 

Huh? 

A little bit of background is in order. I recently acquired 
a 512K upgrade for what I had affectionately dubbed my 
"Meager Mac." Needless to say, one of the more exciting 
things about owning a Fat Mac is having the ability to run 
Switcher. I had a copy of Switcher 2.0 (ancient history, yes, I 
know) lying around which I immediately started tinkering 
with. 

It didn't take long to discover Switcher's ability to create 
"sets" which, when double-clicked from the Finder, would 
launch all of my favorite applications. Now a problem arose: 
how do you specify an application's document ("Write/Paint 
Set," for example) as the startup application? 

Answer: you don't, unfortunately. This frustrated me; it 
would have been really nice to be able to launch my set 
automatically upon bootup. 

Hang on... when you double-click a document icon in 
Finder it knows what application to launch. Why not do 
something similar, like write an application which maintains 
a document name and, when executed (excuse me, launched), 
determines the owner and launches it (passing it a Finder Info 
handle to the document). 

Well, that's the story of Launch Doc in a nutshell. It's 
probably worth pointing out that the version of Switcher that 
I now have (4.4) allows you to start up with Switcher and 
your favorite set simply by calling the set "Switcher.StartUp." 
If you have a set by that name and make Switcher the startup 
application, booting that disk will get you into whatever 
applications you have in the set. Thanks, Andy. 

This doesnt make Launch Doc useless, though. If 
nothing else, Launch Doc came in handy during the last stages 
of its own development, since I used it to cause its own source 
code to be launched whenever I booted the disk. Furthermore, 
I use Launch Doc to launch another very long term 
document/application: my saved game for Infocom's A Mind 
Forever Voyaging! 

Now for an overview: 

There are two INCLUDE directives in the source. The 
first is a must, the second is convenient, but only possible on 
a 512K or higher machine. Failing a 512K system, list the 
file and find the EQUates for CurApName and 
AppParmHandle. They're used by Launch Doc. Use the 
equates instead of the include. 

The globals are straightforward and minimal: a launch 
parameter block, room for a pointer, and room for a short (64 
character, counting the length byte) string. 
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Launch Doc 


Paul F. Snively 
Columbus, IN 
MacTutor Contributing Editor 


E: ^ 


P d 
eS 
P d 


The source assembles to "Buffer.Bin" and resource 
compiles to "Launch Doc." The type is APPL (naturally), the 
creator is LDOC, and the Finder flags are $2000 (the bundle 
bit is set). 

The resources follow. First is the signature. Any Mac 
application that has its own icon must have a signature, the 
icon(s), FREF(s), and a BNDL. 

The icon list follows. I cannot tell a lie: I design my 
icons last, and for testing purposes use a solid black icon. 
After the code is done, I use ResEdit to create my real icon. I 
then launch the application under TMON, use the Load Res 
user area routine to load the ICN for the application, and 
print a dump of the hex codes that make up the icon and its 
mask. I then go back and edit the source to reflect the object 
code. It almost takes longer to describe than to do, and as far 
as I'm concerned, its quicker than using icon editors and 
converters! [Note: Chris Yerga's nifty icon converter package 
in assembly might change your mind. It produces source code 
listings from icon binary files. See MacTutor, Jan. 1986.-Ed] 

Next comes the FREF (file reference) resource. There's 
only one file to refer to with Launch Doc: the application 
itself. Its local ICN# ID is 0. 

Next is the bundle. This is necessary for the Finder to 
install the program on the desktop. 

The remaining resources are the elements of Launch 
Doc's user interface. Ideally, the only one of these items that 
you will ever see is the dialog box, which is used to edit the 
name of the document to launch. The alert boxes are error 
messages; they let you know that something has gone wrong 
somewhere. Possible error conditions include errors writing 
the document name to disk (most likely a disk full error), an 
inability to read the file information for the document (the 
specified document probably isn't on the default volume or the 
document name is null), an inability to launch applications 
(why would you want to? I don't call it Launch Doc for 
nothin), and an inability to find the application that created 
the document (the document is on the volume but the 
application isn't). 

The main program is largely a collection of subroutine 
calls. Ordinarily this would be considered good design, but it 
did cause some problems. My code could be politely described 
as "workmanlike," and if I weren't already past deadline I'd take 
a stab at cleaning it up. This is left as an exercise for the 
reader. 

First all of the managers are initialized with the exception 
of the window manager. I wanted to avoid a double-flicker 
effect from launching Launch Doc and then launching another 
application in rapid succession. The result was several 
_InitWindows throughout the code (anytime a dialog or alert is 
about to come up), but I think it was worth it. 


O The Complete MacTutor, Vol. 2 


GetDocName is an interesting routine. Something that 
most Mac programmers are aware of, but not many seem to 
use, is that an application can have a data fork as an integral 
part of the application. This is great for programs that only 
need one data file. Since I wanted to save a document name on 
a continuing basis, using Launch Doc's own data fork seemed 
like a good idea. This idea is not original with me; the public 
domain game Megaroids uses the same technique to save the 
high score. GetDocName opens the data fork of the current 
application (by using the system global CurApName) and tries 
to read the first 64 bytes of the data fork into the FileName 
global. If the read fails, the routine CLR.B's FileName 
(effectively creating a zero-length string). In any event, the 
local variable structure is dropped and the routine returns. 

EditMaybe' is the heart of the user interface to Launch 
Doc. EditMaybe determines whether the mouse button is 
being held down. If it is not, EditMaybe closes Launch Doc's 
data fork and returns, otherwise it tosses up a dialog box 
showing the current document name and allowing the user to 
edit it and save it or exit to the Finder. 

How? First the _GetNewDialog trap is used to bring up 
the dialog box. _GetDItem is used to get the handle to item 
#4 (the editable text item). — SetIText is used to set the 
dialog's text equal to the string in the FileName global. 
.SellText is used to select the whole item for editing. 
Finally, _ModalDialog is used to interact with the user. 
Thanks to the fact that all other items are disabled, only 
clicking on the buttons or pressing Return or Enter has any 
effect. 

You may have noticed the flim-flamming around with the 
stack on some of the dialog related toolbox traps. The reason 
for this is that the toolbox wants pointers to the parameters, 
not the parameters themselves. Since I refuse to allocate 
global space for something that is only going to be thrown 
away (as a great deal of the _GetDItem info is), I just allocated 
space on the stack and then used the PEA x(SP) instructions 
to push pointers to them. It necessitates some extra mental 
keeping track of the stack, but it's worth it - the end result is 
that the results are on the stack, where they should be. 

_SetIText simply sets a text item to the string passed to 
it. It is used in this instance to make the editable text item in 
the dialog equal to the document name which was read from 
the data fork. 

_SellText is used to select any portion (or all) of an 
editable text item. I used it to select the entire name. This 
causes the dialog to behave in much the same manner as the 
Standard File package or Disk Initialization package, both of 
which select the entire name on editable items. The reason for 
this is that the user, if he or she is going to change anything, 
is likely to change the whole thing. 


_ModalDialog is then used to interact with the user. The 
editable text is disabled, so it can be edited without returning 
to the caller every time an event occurs in that field (we don't 
care abou individual events; we only care about the end result). 
Pressing Return or Enter has the same effect as clicking on the 
OK button. 
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If the user selects OK, EditMaybe uses the  GetIText 
toolbox trap to read the newly edited (maybe) filename into the 
FileName global. It then uses the _ Write OS trap to write the 
string back out to the data fork of Launch Doc. If there was a 
problem with the write, an alert is displayed. EditMaybe 
_Closes the file, checks D4 to see what it should do upon 
returning, and returns. 

If the user selects Finder, EditMaybe closes the data fork, 
checks D4 and returns. 

If Finder was hit or there was a _Write error, the Z flag 
will be set upon returning from EditMaybe and Launch Doc 
will RTS its way to the Finder. Otherwise GetDocInfo will 
be called. 

GetDocInfo uses  GetFileInfo to determine two very 
pertinent pieces of information about the document to launch: 
its type and creator. 

If there was a problem getting the info, an alert box tells 
the story. If you try to launch an application with Launch 
Doc (type = APPL), the same thing happens. 

LoadFileInfo is interesting. There is a little known 
access method on the Macintosh which uses a parameter called 
ioFDirIndex, which is neither more nor less than the number 
of the file on the volume. It so happens that the GetVolInfo 
OS trap returns, among other things, the number of files on 
the volume. Armed with that information and the ioFDirIndex 
means of using  GetFileInfo, LoadFileInfo can get the info on 
every file on the volume without having to know a single 
filename. First, it determines how many files are on the 
volume. It then allocates a pointer large enough to hold all of 
the information for all of the files. A simple loop then reads 
the info into the block. 

FindAppl searches the block containing the file info for a 
file whose creator matches the creator of the document and 
whose type is APPL. If it fails to find such a file, an alert 
gives the user the message, otherwise _GetFileInfo is used 
(again), this time with a pointer to a block for the name, 
which is what we really need (for Launch). 

BuildFInfo customizes the Finder Info handle to represent 
the fact that we want to open a document of whatever type is 
in D6. We only want to open one file, and it's on the default 
volume. The file version number is zero (it always is, 
according to IM) and the name is given. 

Upon returning from BuildFInfo, Launch Doc points AO 
to the Launch parameter block, which in turn points to the 
name of the application to launch. Launch Doc configures the 
parameter block to use the standard screen and sound buffers, 
and Launch is called. 

Thats it! Thanks to BuildFInfo, the application will 
behave exactly as if you had double-clicked on the document's 
icon from the Finder. 

The major concepts embodied in Launch Doc are the use 
of the _GetDltem, SetIText, GetIText, and _SellText traps 
for altering the contents of dialog boxes, the use of the data 
fork of an application for storing recurrent but changing 
program globals (you could, of course, save the entire global 
variable area in the data fork if you needed to), and building the 
Finder Info handle so that the application is forced to open the 
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document. I think that the source code is well-documented; bah Ah auda. 
practically every line is commented and major routines are TECTA 
preceded by a block of comments. HEX QFFFFEOQ OFFFFFOO 
Well, Andy Hertzfeld has made my original motivation HEX OFFFFF80 OFFFFFCÓ 
for writing Launch Doc obsolete, but I'm sure that there will i M AREIA 
be other utilities that I will want to launch a document for HEX ØFFFFFF8 ØFFFFFF8 
upon bootup, and perhaps you will think of some too! HEX OFFFFFF8 OFFFFFF8 
s . HEX OFFFFFF8 OFFFFFFB 
SAVE "Launch Doc.Asm HEX ÜFFFFFFB ØFFFFFF8 
LIST OFF HEX OFFFFFF8 OFFFFFF8 
——————————— HEX OFFFFFF8 @FFFFFF8 
---- HEX OFFFFFF8 OFFFFFF8 
* Launch Doc HEX OFFFFFF8 ÜFFFFFFB - 
* Copyright (c) 1985 HEX QFFFFFF8 OFFFFFF8 
*  MacTutor HEX OFFFFFF8 ØFFFFFF8 
* Written 10/85 by Paul F. Snively HEX OFFFFFF8 OFFFFFF8 
x HEX OFFFFFF8 OFFFFFF8 
* This utility maintains a document file ENDR 
x name internally which it uses to find | *-----7-----7--------------------- 
* the name of the application that created it. RSRC FREF, 128 
x It then creates a “Finder Information Handle" ASC APPL ;File type 
x which it passes to the application as it launches DATA /Ü ; ICN* localID 
x it, thereby causing the application to open the STR ;File name 
* specified document. The primary reason for this ENDR 
* is that documents can't be specified as the startup | *-------70777-7---7-7-------------- 
* application with the Set Startup function in the RSRC BNDL , 128 
* Special menu. ASC "LDOC" ;Signature 
x DATA /0 ;Res ID of autograph 
* Why would you want to start up under a document? DATA [2-1 ;* of res types - 1 
* Easy. If you have Switcher, you probably have at ASC FREF ;Res type 
* least one disk with a couple of your favorite DATA /1-1 ;* of res's - 1 
* applications, Switcher, and a Switcher document DATA /0 ;localID 
* that, when double-clicked, launches your applications DATA / 128 ;Res ID 
x under Switcher. Wouldn't it be nice to be able to specify ASC ICN® ;Res type 
* — that Switcher document as the startup application? DATA /1-1 ;* of res's - 1 
x DATA /0 ; loca1ID 
* "Mater artium necessitas." DATA / 128 ;Res ID 
- Letin proverb : ENDR 
, EEE EEE SSS — TE  -——————————— 
earner nnn nn nnn nnn nn none == - ++ - = -- == +--+ = + ------------ RSRC DLOG, 256 
DATA /108, /1®8, /198, /400 ;boundsRect 
INCLUDE "Library.Asm" DATA 1 ;procID 
INCLUDE "Equates .Asn" ;Only with 512K! DATA #1, 80 jvisible, unused 
aa enka ED ELE DATA 0,80 ; goAwayf lag, unused 
GLOBAL —— 76,$CE DATA 0 ;refCon 
DEFV 8, LParmB1k ;Launch parameter block DATA /256 ; itemsID 
DEFV L,FileList ;Pointer to start of file STR jtitle 
list ENDR 
DEFV 64,FileName ;Name of document d pua ana 
ENDG RSRC ALRT,257 
cd RE ME EUR RM MEE DATA /100,/109,/170, /499 ;boundsRect 
TFILE "Buffer .Bin" DATA 257 ;itemsID 
RFILE —— "Launch Doc", APPL,LDOC, $2000 A /$0101010101010101 — ;stages 
wt MLUSEOEE NR EOD MR t e M aw 
RSRC — LDOC,O a ea rpne D E CE 
STR “Launch Doc 1.8 Copyright (c) 1985 MacTutor" RSRC ALRT, 258 
ENDR DATA /100,/100,/170, /400 ;boundsRect 
g-------------------------—----7-7-- DATA 258 ;itemsID 
RSRC ICN! , 128 DATA /391010101010 10101  ; stages 
HEX ØFFFFFF8 ØFFFFFF8 ENDR 
HEX OFFFFFF8 ØFFFFFF8 Eu e Tera ae 
HEX QFFFFFF8 ØFFFFFF8 RSRC ALRT, 259 
HEX OFFFFFF8 OFFFFFF8 DATA / 108, /108, / 188, /408 ,boundsRect 
HEX gFFFFFF8 OFFFFFF8 DATA 299 ;itemsID 
HEX QFFFFFF8 OFFFFFF8 DATA /301919101901010101 — ;stages 
HEX OFFFFFF8 OFFFFFF8 ENDR 
HEX OFFFFFF8 OFFFFFFS aine a eee 
HEX gFFFFFF8 OFFFFFF8 RSRC ALRT , 268 
HEX OFFFFFF8 OFFFFFF8 DATA /100,/100, / 180, /400 ;boundsRect 
HEX OFFFFFF8 OFFFFFF8 DATA /260 ;itemsID 
HEX gFFFFFF8 gFFFFFF8 DATA /30101010101010101 — ;stages 
HEX 000901188 g9FT711C8 ENDR 
HEX Q9F007C8 QOFFBFCB8 Rae ye EIE ERE a 
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DITL, 256 

/4-1 ;* of items - 1 

g ;Placeholder for item handle 
/10,/29,/90, /80 ;Display rectangle 

84 jitem type (button) 
"OK" ,button contents 


ð Placeholder for item handle 


/10,/100,/90, / 170 Display rectangle 
#4 jitem type (button) 
"Finder" ;button contents 


Ü ;Placeholder for item handle 
/10,/10,/29, /250;Display rectangle 
#8+ 128 


"The current document to launch is:" jstatText 
ø Placeholder for item handle 
/39,/10,/56,/250; Display rectangle 


11164 128 

ss ;editText 

DITL, 257 

/2-1 ;" of items - 1 


Ü ;Placeholder for item handle 


/45,/230, /65, /290 ;Display rectangle 
84 jitem type (button) 
"OK" ;button contents 


0 ;Placeholder for item handle 
/ 10, /55,/29, /325;Display rectangle 

88+ 128 jitem type CstatText) 
"I couldn't save the document name!" 


DITL, 258 

/2-1 ;" of items - 1 

Ü ;Placeholder for item handle 
/45, /238, /65, /290 ;Display rectangle 

84 jitem type (button) 
"OK" jbutton contents 


;Placeholder for item handle 
;Display rectangle 

jitem type CstatText) 
"I couldn't get info on the document!" 


ø 
/18,/55,/29, /325 
#8+ 128 


DITL, 259 

/2-1 ;"* of items - 1 

ø ¿Placeholder for item handle 
/55, /238, /75, /290 ,Display rectangle 

84 jitem type (button) 
"OK" ;button contents 


Ü ;Placeholder for item handle 
/10,/55,/51, /325;Display rectangle 
88+ 128 jitem type CstatText) 


"I can only launch documents, not applications!" 


DITL,260 

/2-1 ;" of items - 1 

ð ;Placeholder for item handle 

/55, /238, /75, /290 ;Display rectangle 

84 jitem type (button) 
"OK" ;button contents 


l^ Placeholder for item handle 
/19,/55,/51,/325;Display rectangle 

88* 128 jitem type (statText) 
#58 ,String length 

"I couldn't find the application " 

"that created the document!" 


; T E A E A EEE ee i 


START 


edit 


BSR 
BSR 
BSR 


1,52 
InitManagers ;Standard Initialization 
GetDocName ;Get name of document 
EditMaybe ;Allow for opportunity to 
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BNE.S NoExit ,We don't want to leave yet 
Exit RTS ; This gets us back to Finder 
NoExit BSR GetDocInfo ;Get document information 
BNE.S Exit ;If there was a problem 
BSR LoadFileInfo  ;Get the goods on all files 
BSR FindAppl ;Find the application for doc 
BNE.S Exit ;1f there was a problem 
BSR BuildFInfo ;Build Finder Info Handle 
LEA LParmBlk(A5),AQ =; Point to launch parm blk 
MOVE.L . 8$0000,4(A0)  ;Screen,sound buffers 
TBX Launch ;, And launch it! 
Rea te —— ——— E, 
* [nitManagers: This routine initializes all major managers 
x except for the Window Manager, which is done in 
x EditMaybe if necessary. The reason for this is 
* that in most instances Launch Doc will simply do 
* its thing (which involves no video output at all) 
* end Since the application that it launches will 
x undoubtedly do an _InitWindows, the double flash 
x 


would be both annoying and redundant. 


InitManagers PEA 
TBX 


-4(A5) ¿Standard Init Sequence 
InitGraf ;Init QuickDraw 
TBX InitFonts ; Init Font Manager 
MOVE.L "$0000FFFF,0U ;Flush all events 
0ST FlushEvents 
CLR.L -(SP) ,No restart procedure 
TBX InitDialogs ; Init Dialog Manager 
TBX TEInit ;Iinit Text Edit 
TBX InitCursor ;Use arrow cursor 
RTS 


* GetDocName: Reads the document name into a global 


* string variable from the data fork of the application. 
* Uses: AZ, A1,A6,D3 
GetDocName LINK A6,%-59 ;08 bytes of local vars 
LEA -50CA62,A8 ;Point to data structure 
CLR .W 22(AQ) ,Use default volume 
CLR.B 26CAQ) ;File version Ø 
CLR.L 28CA0) ,Use vol buffer 
LEA CurApName, A 1 
MOVEA.L Al, 18CA@) ,Use current app] name 
OST Open ;Open the file 
MOVE.W  24(A0),D3 ; ioRef Num 
MOVE.L 864,36CA2) ;Try to read 64 bytes 
LEA FileName(A52,A1 
MOVEA.L — A1,32CA0) ;Where to store 64 bytes 
MOVE.W 81,44CA0) ;Relative to beginning of 
file 
MOVE.L .— 80,46CAD) ,Very beginning of file 
OST Read ;Read the document name 
TST.W 16CA0) ;Everything OK? 
BEQ.S .1 ,6o if so 
CLR.B FileName(A5)  ;Else make null string 
.1 UNLK A6 ,Urop data structure 
RTS ,And return to caller 


* EditMaybe: A complex routine that checks if the mouse 


button is being held down and, if it is, opens a 
dialog box which displays the current document 
to launch and allows the user to edit it. If the 
user clicks OK, the new filename is written to the 
data fork of the application. Otherwise, the write 
is bypassed. A flag is set accordingly, which upon 
returning from the subroutine will either dump the 
user back into the Finder or continue with the launch. 
A®,A1,A2,A6,04,05,D6 


Edi tMaybe 


LINK A6,#-59 
-5ØC(A6), A2 
-(SP) 
Button 
(SP)*,D4 
2 


;5Ø bytes of local variables 
;Point to data structure 
,Room for toolbox Boolean 
,Is the mouse button down? 
;Retrieve result 

360 if no mouse down 

¿Needed for dialog box 
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LEA 
CLR.W 
TBX 
MOVE.W 
BEQ 


TBX InitWindows 


CLR.L -(SP) ;Room for result 
MOVE.W %$100,-CSP) ;,Dialog * 256 
CLR.L -(SP) ;Let system allocate memry 
MOVE.L — 8-1,-CSP) ;Put in front 
TBX GetNewDialog  ;Get the dialog box 
MOVE.L (SP)*,D5 ;Get result (Dialog Ptr) 
CLR .W -CSP) ;Room for itemType 
CLR.L -CSP) ;Room for itemHandle 
CLR.L -CSP) ;Room for dispRect 
CLR.L -CSP) 
MOVE.L D5,-CSP) ;Dialog Ptr to stack 
MOVE.W — 84,-CSP) jItem * 4 (Editable Text) 
PEA 18CSP) ,ADDR of itemType 
PEA 18CSP) ;ADDR of itemHandle 
PEA 14CSP) ;ADDR of dispRect 
TBX GetDItem Cet Dialog Item 
MOVE.L — 8CSP2,D6 ;Get handle 
ADD . W 8 14,9P ;Drop result 
MOVE.L D6,-CSP) ;,Handle to Item 
PEA FileName(A5)  ;String 
TBX SetIText ,Meke Text Item = File Name 
MOVE.L — D5,-CSPD ;Dialog Ptr to stack 
MOVE.W %4,-CSP) ;Item #4 (Editable Text) 
MOVE .W #9, -CSP) ;From position Ø 
. MOVE.W %64,-CSP) ;To position 64 (whole thing) 

TBX SellText ;Select the text 
CLR .W -(SP) ;Room for result of dialog 
CLR.L -(SP) ¿No filter proc 
PEA 4CSP) jPtr to result 
T8X ModalDialog ;Get answer from user 
MOVE .W CSP )+,D4 ;Get result of Modal Dialog 
SUBQ.W 1,04 ;Wi1l be EQ on "OK" 
BNE sl ;Bypess write 
MOVE.L D6, -CSP) jHandle to text item 
PEA FileNameCA5)  ;String 255 of File Name 
TBX GetIText Get the new File Name 
CLR.L 12CA2) ;,No completion routine 
MOVE.W 03,24CA2) ; ioRef Num 
LEA FileNameCA52,A1 ;Point to buffer 
MOVE.L — A1,32(42) ;Buffer to write from 
MOVE.L  %64,36CA2) Write 64 bytes 
MOVE.W  %1,44CA2) jRelative to start of file 
MOVE.L 89,46CA2) ;Beginning of file 
MOVEA.L — A2,A0 ;Move to AØ for OSTrap 
OST Write Write string 
MOVE .W 16(A25,D4 ;1s everything 0K? 
BEQ .1 ;Go if ok (Z set) 
CLR .W -(SP) ;Room for result of alert 
MOVE.W  %$101,-CSP) ;AMert 8 257 
CLR.L -(SP) ;No filter proc 
TBX StopAlert ;Do Alert 
ADDQ .W %2,SP ;Drop result 

1 MOVE.L D5,-CSP) ;Dialog Ptr to stack 
TBX DisposDialog  ;Done with dialog 

2 CLR.L 12(42) ;No completion routine 
MOVE.W D3,24CA2) ; ioRefNum 
MOVEA.L A2,A0 ;Move to A0 for OSTrap 
OST Close ;Close the file 
TST.W D4 ;Set flags 
UNLK A6 ;Urop data structure 
RTS ;And return to caller 


* GetDocInfo: A routine which determines the type and 


* creator of the document to launch. 


D6 
x and the creator in D7. 
* Uses: 


AG, A1, A6,DØ, D6,D7 


It returns the type in 


GetDocInfo LINK A6,#-88 ;80 bytes of local variables 
LEA -80(A6), A0 ;Point to data structure 
CLR.L 12C(A0) ;No completion routine 
LEA FileNameC(A5),A1  ;Pointer to filename 
MOVE.L — A1,18(A0) ;Put pointer in data 

structure 
CLR 22C(A0) ,Use default volume 
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.1 


on all of the files on the default volume. 


26CA0) 
28CA0) 
GetFileInfo 
32C(A0),D6 
36CA2),D7 
16CA2) 

"m 
InitWindows 
-(SP) 
"$192, -CSP) 
-(SP) 
StopAlert 
"2 SP 


3 
1$4150504C,D6 
2 


InitWindows 
-(SP) 
%$103,-CSP) 
-(SP) 
StopAlert 
#2, SP 
#-1,DØ 

4 


89 DO 


;File version 8 Ø 

j Index 8 Ø 

;Get the information 

;Get file type 

;Get file creator 

What was the result? 

; 6o if no problem 

;Needed if not done before 
;Room for result of alert 
;Alert ® 258 

;No filter proc 

;Do Alert 

;Drop result 

;Exit this routine 

;Is type = APPL? 

If not, go ahead 

;Needed if not done before 
;Room for result 

;Alert # 259 

No filter proc 

;Do Alert 

;Drop result 

;Reset Z flag 

;Leave 

;Set Z flag 


;Drop data structure 


* LoadFileInfo: 
x 


;And return to caller 


A routine which loads all of the information 


Uses the 


not well known "ioFDirIndex" access mode to get 
info without knowing filenames. 
AG, A6,08,03 


CLR.L 
CLR.W 
CLR.W 
OST 

MOVE .W 
MOVE .W 
EXT.L 


MULU 889, Dd 


ADDA.L 


SUBQ #1,D3 
.1 


BNE.S 


LoadFileInfo LINK A6,#-64 
LEA 


-64CA62, A0 
12CA2) 

22( AB) 
28(A0) 
GetVolInfo 
40CA0),D3 
D3,D60 

DØ 


;64 bytes of local variables 
;Point to data structure 

;,No completion routine 
;Default volume 

;Use ioVRefNum only 

;Get the volume info 

;Get * of files on volume 
;Copy it to DØ 

,Meke it long 


How much room for file info 


NewPtr ;Create new pointer 
A®,FileListCA5)  ;Save pointer 

12CA0) ;No completion routine 
18CA0) SNIL name pointer 

22(A0) ,Use default volume 
26(A0) ;File version ® Ø 
D3,28CA0) ,ioFDirIndex * goes here 
GetFileInfo jGet the file information 
8580 , Ad Point to next block 


Next file 8 


;Do it again 


;Drop data structure 


;And return to caller 


x FindAppl: A routine which searches the file info list for 
x the application which created the document to launch. 
* Uses: A0,A1,D0 
FindAppl MOVEA.L FileList(A52,A0 ;Get pointer 

OST GetPtrSize ;How big is block? 


MOVEA.L — D0,A1 ;Move size to Al 
ADDA.L — AQ,A1 ;Point past end of block 
.1 CMP.L 36CA02,07 ;Same creator? 
BEQ.S 2 ;6o if so 
.4 ADDA .L 380, A0 ,Next info block 
CMPA.L AQ,A1 ;Done? 
BNE.S "i ;If not, continue 
TBX InitWindows ;Needed if not done before 
CLR. W -(SP) ;Room for result of alert 
MOVE.W %$104,-C(SP) ;Alert #8 260 
CLR.L -(SP) No filter proc 
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TBX StopAlert jDo Alert OST SetHandleSize ;Set the handle size 
82 SP 


ADDQ .W p ;Drop result MOVEA.L CA@),A1 ,Dereference the handle 
MOVEQ 8-1, D5 ;Reset Z flag CLR .W (A1) ;Open file 

.9 MOVE.L — FileList(A52,A0  ;Get pointer MOVE.W — 81,2(AD One file 
OST DisposPtr ;Get rid of it CLR.W 4(A1) Default volume 
TST.L D5 ;Set flags MOVE.L 06,6CA1) ;File type 
RTS ;Return to caller CLR.B 19CA 1) ;File version # Ø 

2 CMP.L 1$4150504C,32(A0) ;Is type APPL? MOVE.B — FileName(A52,DO ;Length of filename 
BNE.S 4 ;Go if not ADDQ 11,09 ;Add one for length byte 
MOVEA.L — A2,A1 ;Copy pointer LEA 12(A1),A1 ;Point to filename area 
MOVE.L  #64,DØ ,04 byte block LEA FileNameCA5),A@  ;Point to filename 
OST NewPtr ,Meke new pointer 0ST BlockMove ,Move the name 
MOVE.L A@, 18CA1) ;Store the pointer RTS ;Return to caller 
MOVE.L — A1,48 ;Back to Ag k-------------------------------- 
OST GetFileInfo ;Get the name this time ENDR 

MOVE.L 18CAQ),LParmBikCA5) ;Move pointer to globals K-------------------------------- 

CLR.L D5 jSet Z flag SEG 0,32, VAR.LEN, $20 
BRA.S 3 Exit Boman nn nnn nnn -= 

k-------------------------------- SEG 

* BuildFInfo: A routine which builds the Finder Info handle to SEG_1 JP START, 1 

x pass to the application, causing it to Open the END_1 

x specified document. ENDS 

* Uses: A0,A1,D0 ENDR 


BuildFInfo MOVEA.L AppParmHandle,A® ;Finder info handle 
MOVE .L 8 13, DO ;Constant size value END 
ADD .B FileNameCA5),08  ;Adjust for filename len. 
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Ask Prof. Mac 


Readers Technical Questions 


PICTs from MacDraw 

Q. Mike LePage would like to know if a MacDraw PICT 
file is really a QuickDraw picture; more generally, he asks 
how to get a MacDraw picture into a PICT resource that his 
application can use. 

A. I really don't know what file format MacDraw uses; its 
PICT format sure doesn't look like a QuickDraw picture to 
me, but it may have such pictures buried within it. At any 
rate, a good way to get a PICT resource from a MacDraw 
document is to paste the drawing into the Scrapbook; it will 
be a PICT resource in the Scrapbook file, which can then be 
moved to your application using Copy/Paste within ResEdit. 

[Note: ResEdit is available on source code disk #6 for this 
issue of MacTutor. -Ed.] 

Drawing Partial Pictures 

Q. Mike LePage also asks, "Suppose I have a giant picture, 
but want to display only part of it in a window and not have it 
all scaled down into the window, with the rest able to be 
scrolled into view. Is there a way of setting the bounds 
rectangle without creating a bit image of the whole picture 
first?" 

A. What I'd do is pass a bounds rectangle to DrawPicture 
that was as large as the whole picture. The drawing will be 
clipped to the window's rectangle, so only the part of the 
picture that is in the window will actually be drawn, and it 
will not be scaled down. To scroll, use ScrollRect, and draw 
the picture again with the boundsrect moved by the size of the 
scroll. 

Simple FilterProc 

Q. Mike LePage's third question is, "I have a FilterProc for a 
modal dialog ‘About’ box. I don't want any buttons or other 
controls, so the function will just check for a mousedown and 
return True on that condition only." Mike wants to know 
how to code such a FilterProc in assembler. 

A. I'd suggest that such a function also return True if Return 
or Enter is pressed. So, that's the way I've coded it in Figure 
1. 

Resources Potpourri 
Q. Pascal M. Giordano has a lot of questions about 
resources, so many that it would take too much space to list 
them all. So, in this case I'll provide only some answers 
without the questions! 


A. OpenResFile is used to open a resource file and make 


the resources in it available to your application, typically via 
GetResource. When your application is launched, its resource 
fork is automatically opened. So, you only need to use 
OpenResFile to get at resources in a file other than your 
application. Some developers like to maintain their non-code 
resources in a separate resource file while they're working on 
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Steve Brecher 
Software Supply 
MacTutor Contributing Editor 


the program, because code changes are much more frequent 
than resource changes. Hence, they must use OpenResFile to 
make 


Figure 1 


Function MyFilterCtheDialog: DialogPtr; 
VAR theEvent: EventRecord; 
VAR itemHit: INTEGER): BOOLEAN; 


ModalDialog filterProc which returns True if the event is a 
mousedown or Return or Enter key. 


Wwe We We We He cil 


Include SysEqu .D 
b 
; ASCII codes 
CR Equ 1 
Enter Equ 3 
; A6 offsets-- 
01dA6 Set ð 
RtnAddr Set 01dA6+4 
itemHit Set RtnAddr+4 
theEvent Set itemHit+4 
theDialog Set theEvent+4 
Result Set theDialog*4 
MyF ilter: 
Link A6, #0 set up stack frame 
Move.L theEventCA6), Að AO := addr of event record 


Cmp 8MButDwnEvt, CAO) ;mousedown? 
;(note evtCode offset = 0) 
; remove following 6 instructions if key events not to be 


tested 


Beq.S — eg ;yes 
Cmp ®*KeyDwnEvt, CA) pkey down? 
Bne.S 60 no 
Cmp.B ^ *"CR,evtMessage*3(A0) “Return? 
Beq.S 60 ,yes 
Cmp.B X "Enter,evtMessage*3(A0) ; ‘Enter? 

eü Seq Result(A6) ;set result 
Unik A6 
Move.L (SP)+,A8 ;return address 
Lea Result-itemHit(SP),SP ;pop arguments 
Jmp (A0) ;return 


those resources available. When the program is ready for 
release, the resources are included in the application file and 
the call to OpenResFile is removed. My own approach is to 
have a separate resource file, but to include the resources in 
my application file each time I link a test version. This 
requires a linker which will directly include resources, such as 
Consulair's Link or Signature Software's McAssembly; MDS 
Link won't do this (it will only include resources that are in 
.REL format). That way, I can create or change my resources 
directly using ResEdit or ReEdit, without a separate resource 
compiler step. 

I very rarely use RMaker. The current version of ResEdit 
is quite good for creating and editing many kinds of standard 
resources. I use ReEdit primarily for editing text items in 
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DITLs, since it provides a bigger editing box than ResEdit 
does for such items. RMaker is a resource compiler that 
translates textual descriptions of resources into actual 
resources. In olden days it was the only way to create 
resources; but as ResEdit matures in its long march to 
completion it becomes a better and better replacement for 
RMaker. [Resources can also be coded in assembler and 
assembled and linked under MDS, as previously mentioned. 
There is also some new software showing up that allows 
dialogs and windows to be "designed" on screen with the 
mouse and then automatically translated into RMaker text file 
format. A lot more work is needed in this area. -Ed.] 

"Signature" is the name for the 4-byte code associated 
with an application. "Creator" is the name for the analogous 
code associated with a document. Usually, they are the same 
code, serving to link the document with it's creating 
application. Often, "Creator" is used in the sense of 
"Signature," as when one speaks of "the application's Type 
and Creator codes." 

A BNDL resource is required in any application that is to 
have a custom icon displayed by the Finder, or in any that 
creates documents that need to be associated with the 
application (so that opening the document automatically 
launches the application). 

Building an Editor 

Q. Dr. K. Desikachary is developing a multilingual editor to 
process Indian Languages. He has several questions; again, I'll 
just imply the questions in my responses. 

A.  MacWrite file formats are documented in Apple's 
Technical Notes #11 (MacWrite 2.2) and #12 (MacWrite 4.5). 
The Technical notes are available by subscription at $20/yr 
from Apple Computer, 20525 Mariani Ave MS 3-T, 
Cupertino CA 95014. 

I haven't seen any documentation of Microsoft Word file 
formats. 

AS far as I know, Apple's Core Edit package is the only 
text editor building-block available. (Dr. Desikachary would 
like to find an editing package that he could build on that 
doesn't have Core Edit's limit of 100 font/style changes in a 
document) I haven't seen Core Edit, but I wonder if the limit 
could be increased by changes to the code. Any reader who can 
be of help on this may contact Dr. Desikachary at 13 
McGregor St., Pinawa, MB ROE 1L0, Canada. 

Finding All Files 

Q. Bob Perez, author of VMCO (Visual/Vocal MAUG 
Conferencing program), wants to know how to find a file on 
an HFS-formatted volume, no matter in what directory the file 
may be. 

A. The FCensus routine in Figure 2 can be used to do this. 
However, rather than search for a given file, it supplies 
information about each file, one at a time, to a routine that 
you supply. If you're looking for a specific file, your routine, 
when it recognizes a match, can tell FCensus to quit by 
returning True. 

Note, however, that on an HFS volume there can be 
more than one file having the same name but in different 
directories. So, searching for a file on an HFS volume and 
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stopping the search when you find the first instance of "the" 
file is a risky thing to do. Maybe the user really wants you to 
use another version of the file, with the same name, that's in 
another directory. 

We use the new HFS routine _GetCatInfo, which is like 
_GetFileInfo except that it returns information for directories 
as well as files. The parameter block that it returns for files is 
the same as the GetFileInfo parameter block, except that it's 
longer — it has extra information appended to it. (Purists 
note: GetCatInfo's ioTrap field in the parameter block header 
is different from GetFileInfo's.) 

"setSound" Code Bumming 

Some CompuServe MAUG members were asking for a 
desk accessory that would let them change the Mac's sound 
volume with less memory overhead than required by the 
Control Panel. Sysop Bill Steinberg obliged by whipping out 
a "SetSound" DA. This was Bill's first DA, so he started with 
Bill Bond's and Chris Allen's DA Shell from the October, 
1985 issue of MacUser magazine, and added the SetSound 
functional guts. When he'd finished, he asked me if I'd like a 
copy of his source code (Bill has always been generous about 
Sharing source code with me). I said sure, and, knowing that 
small size was one of the objects of this exercise, asked him if 
he'd like me to see if I could further reduce its size. He 
thought it'd be tough to take much code out of it without 
changing its functionality -- so much so that he bet me a 
dinner that I couldn't reduce it by 50 bytes. It was originally a 
little less than 1K, so that was about 5%. 

As I watched the code go by at 1200 baud while I Was 
downloading it, I wasn't confident about winning the bet — 
until I saw the 256-byte statically-allocated string buffer at the 
end. I knew then that just by allocating that dynamically, on 
the stack, I could win a free dinner. But I thought Bill might 
object to such a simple maneuver as the sole basis for 
determining who picked up the dinner tab. After all, moving 
the buffer from the DRVR resource to the stack didn't really 
reduce the total memory requirements of using the DA. SoI 
got to work and massaged the code, taking out a word here, a 
few words there. The end result was 414 bytes smaller than 
the original. Of course it's a little obscure in places — the 
inevitable result of optimizing ("bumming") code as much as 
possible. 

The original version is shown in Figure 3a, and the space- 
optimized version in Figure 3b. Comparison of the two 
might provide some useful tips to students of assembly 
language — especially in light of the fact that Bill's original 
version was competently coded, rather than a begining 
programmer's strawman. Thanks to Bill for being a good 
sport, for his permission to reprint the code, and for his wide- 
ranging knowledge of good restaurants. 

Product Briefs from Ms. Elaine E. 

My trusty (if somewhat disorganized) assistant, Ms. 
Elaine E., has returned from a trip outside the cave with 
reports on some products of interest to developers... 

MacExpress 

MacExpress is a "generic application" which provides 

many powerful facilities for handling events, windows, and the 
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desktop. Conceptually, it's a core application program that 
you customize. It handles all the chores of event processing, 
menu selections, window manipulation, etc. that are not 
specific to your application; you provide the code that's 
application-specific. It's supplied as a set of library routines 
for a variety of development systems (MDS, Mac C, TML 
Pascal, etc.) Note that these are not merely utility routines 
that you call for occasional services; an applicatiion built 
using MacExpress would, by virtue of that fact, necessarily 
invoke many of its fundamental event- and window-handling 
routines. Logically (but not physically) speaking, it's as if 
you begin your work with the MacExpress code already 
constituting the core of your application. Physically, your 
code consists of calls to MacExpress routines that are brought 
in at link time (plus, of course, your application-specific 
code). 

For example, MacExpress automatically handles window 
movement, resizing, scrolling, splitting into panes; you have 
to worry only about what gets drawn in the windows. 
Similarly with menus: MacExpress handles command 
selection and desk accessories; you worry only about the code 
that implements the application-specific menu commands. 

MacExpress also provides automatic facilities for 
handling icons on the desktop (Finder-style). You can 
associate icons with, e.g., windows (documents) and/or desk 
accessories. MacExpress will take care of handling the icons 
graphically (dragging them, "shadowing" them, rearranging 
them with a clean-up command); you specify what happens 
when a user opens an icon or sets it aside. 

I haven't actually developed an application using 
MacExpress, but I've spent some time examining the 
documentation, demos, and sample source files that come with 
it. I'd seriously consider using it for a window-oriented 
application. (Lately, my nose has been buried in device 
drivers and such.) MacExpress author Al Whipple appears to 
have a sincere commitment to supporting the product. 

ALSoft, Inc. 

P.O. Box 927 

Spring, TX 77383-0927 (713) 353-4090 

$495 (demo version, $50, applicable to purchase) 

$100/yr per application you distribute (unlimited copies) 


McAssembly 

McAssembly is a new assembly-language development 
system for the Macintosh. It consists of a two-pass assembler 
and linker (integrated into one application file), and a separate 
debugger (Macsbug-style, i.e., TTY line-oriented). 

The assembler has some nice features: dummy data 
sections to facilitate record offset definitions; based variables, 
so that explicit register references need not be coded; 
alphanumeric local labels; decent listings (ever looked at an 
MDS Asm listing? --yuk) with optional cross-reference; built- 
in resource compiler — the assembler knows about the 
formats of the commonly-used resources. Conversion of 
MDS Asm source files to McAssembly format is pretty 
straightforward. 

The linker can directly include resource files (created, e.g., 
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with ResEdit). McAssembly's .Rel file format is not 
compatible with anything else, but a utility is provided to 
convert its .Rel files to MDS format. 

Equivalents for the Software Supplement equate and trap 
definition files are provided, as are .Rel files (in McAssembly 
format) corresponding to the Supplement Appletalk, Printer, 
etc., object files. 

On paper, I like it better than MDS Asm (I've never been 
a fan of MDS Asm) Next time I start a new assembly 
project, I plan to give it a real tryout. Its been used to 
assemble itself and the TMON User Area (which uses every 
trick in the book), so I figure it's reasonably well-tested. 
Author Dave McWherter is responsive to enhancement 
suggestions. 

Signature Software 

2151 Brown Ave. 

Bensalem, PA 19020 (215) 639-8764 

$89.95 

QUED 

QUED is a programmer's text editor. After I bought it, I 
stopped using MDS Edit (and arranged to have Software 
Supply, ie., me, become a dealer for QUED —- note, 
therefore, my financial interest in telling you about QUED). 

QUED is memory-based — the file(s) you edit must fit 
into memory. It will open as many files (windows) as will 
fit; Ive had more than 30 windows open at once. Windows 
can be automatically arranged in a tile fashion (neat rows and 
columns) or stacked in the more usual manner. Each window 
can be horizontally and/or vertically split into independently- 
scrollable panes. The top two windows can be scrolled 
synchronously (scroll bar of either one controls both). 

QUED can be told to automatically save your work every 
N keystrokes, and/or to save to two different disks (called the 
"RAMdisk" option). It will display unclosed parentheses as 
you're entering code, where "parentheses" are user-defined 
program structure elements (begin end, ( }, etc.) or string or 
comment delimeters; or it will check the whole file for 
unbalanced parentheses. It has a user-editable Transfer menu. 
You can move the cursor and/or delete by characters, words, 
and lines without using the mouse. Double-click a window's 
title bar to enlarge it to full-screen; double-click again to 
restore it to its former size. QUED will print in background 
(spooled) mode. You can append to as well as replace the 
contents of the Clipboard, and exchange selected text with the 
Clipboard. Search/replacement can apply to multiple files, 
and Undo really undoes. It's compatible with MDS Edit file 
font, font size and tab-setting resources, and works with MDS 
Exec. 

I like it. I use it. I sell it. The publisher is a good guy 
and is committed to support and enhancements. 

Paragon Courseware 

4954 Sun Valley Road 

Del Mar,CA 92014 (619) 481-1477 

$65 (+CA tax) + $2 shipping, credit cards accepted 

or 

Software Supply 

4618 E. Sixth St. 
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Long Beach, CA 90814 (213) 434-3723 
$65 (CA tax), no shipping charge, checks only 


vRef Num 


DirID 


Wwe Me We We We Ve Wwe e Ve We Ve 


Figure 2 


FCensus -- HFS/MFS file census routine; provides info on each file 
on a volume, whether MFS or HFS. If HFS volume, provides info on each file 
in each directory. 


Procedure FCensus(vRef Num: integer; DirID: longint; Inspector: ProcPtr); 


volume reference number (or drive number) of volume. 


ID of directory in which to begin search; pass 2 for root directory. 


The designated directory and all directories below it in the tree will 


Inspector 


"wc o Be We Be We we. wow. 9e 9e 9e 9o 9e We We We Ge 


NOTE: 


Include 
Include 
Include 


be canvassed. Value passed is immaterial for HFS volumes. 


The address of a caller-supplied function: 

My Inspector (ParamB lock: ParmBlkPtr; DirID: longint): boolean; 
ParamBlock is the address of a GetFileInfo parameter block for a 
file on the volume. DirID is the ID of the file's directory Cif the 
volume is an MFS volume, DirID is whatever was passed to FCensus). 
If the Inspector function returns True, FCensus will return 
immediately; otherwise FCensus will continue canvassing Ccontinue 

to cell MyInspector) until all files have been processed. 

after FCensus returns neither the parameter block, nor the 
the filename string pointed to by its ioFileName paremeter, exists. 


The census is depth-first, i.e., directories within directory X are 
canvassed before other directories within X's parent directory. Within a 
directory, files are accessed in alphabetic order; then directories within 
that directory are accessed in reverse alphabetic order. 


MacTraps.D 
SysEqu.D 
SysErr .Txt 


not provided in pre-HFS SysEqu/MacTraps: 


ioDirID 


Equ 48 
ioHFQE1Size Equ $6C 
ioDirFlg Equ 4 
FSFCBLen Equ $3F6 ,8ddr of sys global, positive if HFS running 
Trap -HFSDispatch $4260 
Macro -GetCatInfo = 
MoveQ #9 Dg ,Selector 
"eae 
; A6 offsets-- 
01dA6 Set Ü 
RtnAddr Set 01dA6*4 
Inspec Set RtnAddr +4 
Dir ID Set Inspec*4 
vRef Num Set DirID*4 
ArgsSz Set vRefNum+2- Inspec 
ParmBlk Set 01dA6- ioHFQE1Size ; local parameter block 
NameStr Set ParmB 1k-256 ; local filename string buffer 
Index Set NameStr-2 ; index in current directory 
FCensus: 
Link A6,® Index 
Cir.L -(SP ) ,Sentinel for end of DirID list 
NextDir: 
Cir IndexCA6) jinit index 
NextF ile: 
Lea ParmB1k(A6), AQ ;pointer to param block 
Move vRefNumCA6), ioVRef Num(AQ) 
Move.L DirIDCA6), ioDirIDCAQ) 
Lea NameStr(A6),A1 
Move .L A1, ioF i leNameC AQ) 
AddQ #1, IndexCA6) ,bump index for _GetCat/FileInfo 
Move IndexCA6), ioFDir Index (Ad) 
Tst FSFCBLen ,HFS running? 
Bni.S eg 
-GetCatInfo ,yes 
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eg 
e1 


Bra.S 


-GetFileInfo 


Cir 
Pea 
Move.L 
Move.L 


e1 


NodeK ind 
#fnfErr,DØ 
FCExit 
CSP)+,DirIDCA6) 
NextDir 

FCExit 


$ioDirFlg,ioFlAttribCA0) 
CallInspec 

ioDirIDCAB), -CSP) 
NextFile 


-CSP ) 
ParmB1kCA6) 
DirIDCA6), -CSP) 
Inspec(A6), Ad 
CAD) 

(SP )+ 

NextFile 


A6 

CSP )+, A 
ArgsSz(SP ), SP 
(A0) 


;no error 


;end of current directory? 
;no, an unexpected problem 
;ID of dir to seerch next 
;go look et first file/dir in new dir 


;no more directories, all done 


sis this a directory or a file? 


38 file 


;8 directory, push on search list 


jand loop back 


;space for user function result 
; param block ptr to user func. 


;pass DirID 


;address of user function 


;call user function 


;user wants us to quit now? 


;no, keep going 


;return addr 
;pop arguments 
;return 


L E E e e M 


Resource 


Include 
Include 
Include 
Include 
Include 


. TRAP 


GoodByeK iss 


TRUE EQU 
FALSE 


DAStart: 


DC.W 


DC.W 
DC.W 


DC.W 
DC .W 
DC.W 
DC .W 
DC.W 
DC.W 
DC.B 
DC.B 
„ALIGN 


DAOpen: 


MOVEM.L 
MOVE.L 
PEA 


Figure 3a 


'DRVR' 31 'SetSound' 


MacTreps.D 
SysEqu.D 
QuickEqu.D 
ToolEqu.D 
SysErr .D 


-CntrLi 
EQU =i 


1 
EQU Ü 


$4204 


$4400 


Ü 
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ð 

DAOpen -DAStart 
DAPrime -DAStart 
DAControl-DAStart 
DAStatus -DAStart 
DAClose -DAStart 


8 
'SetSound' 
2 


FON We We We We We We We We Be ls b we We Ce 


A0-A6/00-DT , -CSP) ; 
A1,A4 ; 
SavePort : 


SetSound DA Coriginal version) 
Copyright 1985 William P. Steinberg -- reprinted by permission. 


SetSound is a small (<1K) DA that sets default sound volume 


; Control, Imned 


Flags/descriptor 
Clock in memory, can 
respond Control calls) 


: Tick Count 
: Event mask 


(will handle: keydown, 
update and activate) 
Menu ID 

Offset to open routine 
Offset to prime routine 
Offset to control rout. 
Offset to status rout. 
Offset to close routine 
Desk Accesory title 

( Optional - helps 


identify DA in heap. 


DA appears in Apple 
menu using the 
name of DRVR.) 


Seve registers 
Put DCE pointer in A4 
Save Grafport 


Listing of original version cont. on next page 
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Figure 3b 


f SetSound DA (space-optimized version) 
; Copyright 1985 by William P. Steinberg 
, 

td 


' SetSound is a small (Ø.6K) DA sets default sound volume 


Resource 'DRVR' 31 'SetSound' 


Include MacTreps.D 
Include SysEqu.D 
Include QuickEqu.D 
Include ToolEqu.D 
Include SysErr.D 
Macro Assume Cond = 
If (Cond) 
Else 
Error -- Assumption (Cond) is not true 
Endif 
| 
DAStart: 
DC.W $4400 ; Flags/descriptor 
; (lock in memory, can 
; respond Control calls) 
DC.W g ; Tick Count 
DC.W 328 ; Event mask 
; (will handle: keydown, 
; update and activate) 
DC.W Ü ; Menu ID 
DC.W DAOpen -DAStart ; Offset to open routine 
DC.W DAPrime -DAStart ; Offset to prime routine 
DC.W DAControl-DAStert ; Offset to control rout. 
DC.W DAStatus -DAStart ; Offset to status rout. 
DC.W DAClose -DAStart ; Offset to close routine 
DC.B 8 ; Desk Accesory title 
DC.B 'SetSound' ; (This is optional - helps 
„ALIGN 2 ; identify DA in heap. 
; The DA appears in 
; menu as DRVR.) 
; A6 offsets: 
DriverID Equ -2 
DriverType Equ Driver ID-4 


DriverName Equ 


Driver Type-256 


New source continues on next page... 
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-GetPort 


TST.L dCtlWindowCA4) 
BNE.S GoodOpen ; yes, 
LEA DAStart, Ad 
-RecoverHandle 
MOVE.L AB, -CSP) : 
PEA DriverID 
PEA DriverType ; 
PEA Dr iverName j 
-GetResInfo 
SUB.L 84 SP : 
CLR.L -CSP) f 
PEA WindowRect j 
PEA Dr iverName : 
MOVE.B "FALSE, -CSP) 
MOVE.W #noGrowDocProc,-(SP) ; 
MOVE.L 8-1,-CSP) i 
MOVE .B 8 TRUE, -CSP) ; 
CLR.L -(SP) E 
-NewW indow 3 
MOVE.L (SP +, DO j 
LEA MyW indow, Ag , 
MOVE.L DØ, CAB) ; 
BEQ.S BadOpen 
MOVE.L MyWindow,A8 : 
MOVE .W 
MOVE.L MyWindow,dCtlWindow(A4) 
GoodOpen: 
MOVE.L SavePort,-(SP) 
-SetPort 
MOVEM.L CSP2*,4A0-A6/D0-D7 
CLR.W DØ ; 
RTS 
BadOpen: 
MOVE.L SavePort,-(SP) ; 
-SetPort 
MOVEM.L (SP2*,4A0-A6/D0-D7 
MOVE .W 5- 1,D0 j 
RTS 
DAClose: 
MOVEM.L A0-A6/D0-D7 , -CSP) B 
MOVE.L A1,A4 ; 
PEA SavePor t ; 
-GetPort 
CloseDA: 
CLR.L -CSP) j 
-FrontWindow 
MOVE. 1 CSP )+, DØ 
DAC lose i: 
TST.L DØ ; 
BEQ.S DAC lose3 
CMP.L MyWindow,D6 ; 
BEQ.S DAClose2 
MOVE.L DØ, Ad 
MOVE.L nextWindowCA2),D0 i 
BRA.S DAC lose 1 
DAClose2: 
MOVE.L MyW indow, -CSP) : 
-DisposWindow 
LR.L dCtlWindowCA4) 
DAClose3: 
MOVE.L SavePort,-CSP) 
-SetPort 
MOVEM.L (SP)*,4A0-A6/D0-D7 f 
CLR. W DØ 
RTS 
DAControl: 
MOVEM. L A0-A6/D0-D7 , -CSP) 
MOVE.L AS, A3 ; 
MOVE.L A1,A4 
PEA SavePor t 
-GetPort 


; Does window exist ? 


DA already open 


; Get handle to the DA 


Get information on DA 
DA id 

DA type = 'DRVR' 

DA name 


Make room for result 
WindowRecord on heap 
address of wind rect 
address of wind title 
Make it invisibler now 
Push window def id 
Window in front 

Give it a goaway box 
Window ref value 
Create the window 

Get the window pointer 
Save window pointer 
Was window created ? 


Set windowKind field t 
the DA RefNum 


dCt Ref NunCA4) ,windowK indCAg) ;Put window 


; ptr in the DCE 
; Restore Grafport 

; Restore registers 
Return code 

Restore Grafport 


; Restore registers 
Return code 


Save registers 
Device Ctrl Entry in A 
Save Grafport 


Get front window ptr 
any more windows ? 

Is this our window ? 

Get next wind in chain 


Throw away window 

; Window gone, tell DCE 
; Restore Grafport 
Restore registers 


; Return code 


; Save registers 


ptr to parm block in A3 


, pointer to DCE in A4 
; Save Grafport 


Listing of original version cont. on next page 
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; note functional change if failure, 


return OpenErr instead of -1 


DAOpen: 
Link A6, "Dr iverName 
Move.L (452,42 ; A2 := addr of QD globals 
Assume thePort = Ø 
Move.L (A22, -CSP) ; Save thePort on stack 
MOVE.L A1,A4 ; Put DCE pointer in A4 
MoveQ "9 DØ ; Make open- resultsnoErr 
TST.L dCtlWindow(A4) ; Does the window exist ? 
BNE.S OpenDone ; If yes, the DA was opened 
LEA DAStart,A0 ; Get handle to the DA 
-RecoverHandle 
MOVE .L AB, -CSP) ; Get information about DA 
PEA Driver IDCA6) ; DA id 
PEA Dr iver Type(A6) ; DA type = 'DRVR' 
PEA Dr iverName(A6) ; DA name 
-GetResInfo 
SubQ "4 SP ; Make room for result 
CLR.L -(SP) ; WindowRecord on heap 
PEA WindowRect ; address of window rect 
PEA Dr iverName(A6) ; address of window title 
Cir -CSP) ; Make it invisible now 
MOVE . W "noGrowDocProc,-CSP) ; window definition id 
MoveQ 8- 1,00 
MOVE.L D,-CSP) ; Window appear in front 
MOVE.B DØ, -CSP) ; Give it a goaway box 
CLR.L -(SP) ; Window ref value 
-NewWindow ; Create the window 
MoveQ "OpenErr , DO , Assume failure 
MOVE.L (SP)+,D1 ; Get the window pointer 
BEQ.S OpenDone 
LEA MyW indow, A 
MOVE.L D1, CAS) ; Save window pointer 
Move.L D1,A0 
MOVE.W dCtIRefNumCA4), windowKind(Ag) 
MOVE .L AG, dCtlWindow(A4) ; window pointer in DCE 
OpenDone: 
Move.L (SP )+, CA2) ; Restore thePort 
Unlk A6 
RTS 
DAClose: 
MOVE.L A1,A4 ; Device Ctrl Entry in A4 
Move.L (452, A0 ; Addr of QD globals 
Assume thePort = Ø 
Move.L (A0), -CSP) ; Save thePort on stack 
CloseDA: 
MOVE.L WindowList,D0 
DAClose 1: 
BEQ.S DAClose3 
CMP ..L MyW indow, DØ ; Is this our window ? 
BEQ.S DAClose2 
MOVE.L DØ, Ad 
MOVE.L nextWindowCA2),D0 j Next window in chain 
BRA.S DAClose 1 
DAC lose2: 
MOVE.L DØ, -CSP) ; Throw away our window 
-DisposWindow 
CLR.L dCtlWindowCA4) ; Window gone, tel] DCE 
DAClose3: 
-SetPort 
Bre.S DAexit 
DAContro] : 
MOVE.L A1,A4 ; Put ptr to DCE in A4 
Move.L CA5),A1 ; Addr of QD globals 
Assume thePort = 6 
Move.L (A12, -CSP) ; Save thePort on stack 


; M points to the parameter block which tells US what we 
,need to do and supplies us with the data to carry it out. 


MOVE 
Assume 


csCode(Ad), Dd 
GoodBye = -1 


New source continues on next page... 
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MOVE.L MyW indow, -CSP) ; Make mywindow 
-SetPort ; the Grefport 


; A3 points to the parameter block which tells us what we 


AddQ 
BEQ.S 
CMP .W 
BNE .S 


; need to do and supplies us with the data to carry it out. CTLEvent: 


MOVE csCode(A3), DØ 
CMP . W ttGoodByeK iss, D8 ; "GoodByeKiss" msg 
BEQ.S CloseDA 
CMP .W accEvent, Dd ; Event msg, Sys. Evt. 
BNE .S CTLReturn 
CTLEvent: 
MOVE.L csParamCA3), A2 
MOVE .W evtNum(A2), D8 
CMP .W #keyDwnEvt, DØ ; Keydown event 
BEQ.S EVTkeyDown 
CMP .W tupdatEvt, Dd ; Update event 
BEQ EVTupdateEvt 
CMP .W tactivateEvt, Dd ; Activate event 
BEQ.S EVTactivateEvt 
CTLReturn: 
MOVE.L SavePort,-(SP) ; Restore Grafport 
-SetPort 
MOVEM.L CSP )+, AB-A6/D8-D7 ; Restore registers 
CLR.W DØ ; Return code 
MOVE.L JIODone, - SP) ; Goto IODone 
RTS 
EVTactivateEvt: 
MOVE.W EvtMeta(A2),DØ 
BTST #activeFlag,DØ 
BEQ.S CTLRe turn 
LEA ActivePend, Ag 
ST CAB) 
BRA.S CTLReturn 
EVTkeyDown: 
CLR.L D2 
MOVE.B evtMessage*3(A2),D2 
CMP .B #'9' D2 
BLT.S e2 
CMP .B 8'7' D2 
BGT.S e2 
SUB.B #'9' D2 
ANDI.B #7,D2 
ANDI .B #$F8,SpVolCt] 
OR.B D2,SpVolCt1 
MOVEQ 8T DO 
@1 CLR.L -(SP) 
DBRA 00,81 
MOVE.L SP, A 
MOVE .W "$FFFC,24CA0) 
MOVE.W $2 26CA0) 
MOVE.W D2,28CA0) 
COntrL i 
ADD #32, SP 
LEA SysParam, Ad 
MOVEQ 8-1, 08 
_WriteParam 
MOVE.L MyWindow,-(SP) 
-SetPort 
PEA NumberRect 
-InValRect 
MOVE.W #3,-(SP) ; Beep on update 
_SysBeep ;at current level 
@2 BRA CTLReturn 
EVTupdateEvt: 
MOVE .L MyW indow, - CSP) ; Update MyWindow 
-SetPort 
MOVE.L MyWindow,-(SP) ; BeginUpdate(MyWindow) 
-BeginUpdate 
MOVE.L MyW indow, Ad 
PEA por tRect(Ag) 
_FraseRect 


MOVE. W #' ' -(SP) 
Original source Continues on next page... 
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Lea 
MOVE.L 
MOVE.L 
-SetPort 
Assume 
CMP .W 
BEQ 
CMP .W 
BEQ.S 
CMP .W 
BEQ.S 


CTLReturn: 


_SetPort 
Move.L 
MOVE.L 


DAPr ime: 
DAStatus: 
DAexit: 


CLR.W 
RTS 


EVTactivateEvt: 
LEA 


Move .B 
BRA.S 


EVTupdateEvt: 


eep 


Move.L 
MOVE.L 

Pea 

Move.L 
-BeginUpdate 
Move.B 

Lea 

AND.B 
ADD.B 

Lea 

MOVE.B 
-EraseRect 
MOVE.W 
_DrawChar 
ST 


_SetFontLock 


_TextFont 
MOVE .W 
_DrawChar 
MOVE.W 
_TextFont 
MoveQ 

MoveQ 
Move.L 
-DrewString 
Move.L 
-MoveTo 
Move.B 

Add 

Dbra 
_EndUpdate 
CLR 
-SetFontLock 
Lea 

Bclr 

Beq.s 


MOVE.W 


#1,D9 

CloseDA ; Bye 
taccEvent+1,D8 ; Event msg Sys. Et. 
CTLReturn 

SPVolCt1,A3 ; For later 
csParamCA0), A2 

MyWindow,-CSP) 

evtNum = Ø 

tkeyDwnEvt, CA2) ; Keydown event 
EVTkeyDown 

fupdatEvt, (A2) ; Update event 
EVTupdateEvt 

factivateEvt, (A2) ; Activate event 
EVTactivateEvt 

A4,A1 ; Restore DCE ptr 


JI0Done, - (SP) Goto IODone 


we 


DØ Return code 


we 


ActivePend, Ag 
EvtMButCA2), CA0) 
CTLReturn 


MyW indow, A2 
A2,-CSP) 
por tRect(A2) 
A2,-CSP) 


For EndUpdate 
For EraseRect 


we We 


(A3), D8 
Chars, A2 
CA2)+,D8 ; (87) clr bits 3..15 


SPVolCt] 


Wwe 


(A2)*,D0 ; (8'8') Convert to ASCII 


ASCI IVO] A3 


DØ, CAS) ; Set ASCII volume in message 


€A2)+,-CSP) ; Space 
-(SP) 


Coords, A3 
(A3)*, -CSP) 


sysFont = Ø 
-CSP) 


(A22*,-CSP) ; Copyright symbol 
*applFont,-CSP) 


"9 D4 
84-103 
A2,-(SP) ; Msg addr 


(A3)2*,-CSP) ; Next coords 

; Cone superfluous MoveTo 

CA2)+,D4 ; Bump to next msg... 
D4,A2 

D3, 68 


-(SP) 

Act ivePend, A2 
Act iveF lag, (A2) 
CtlReturn 


"3 -(SP) ; Beep on update at current level 


New source continues on next page... 
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-DrawChar _SysBeep 


MOVEQ #-1 D8 CtlRet: 
MOVE D6,-CSP) BRA.S CTLReturn 
-SetFontLock EVTkeyDown: 
MOVE.L #2Ø<< 16! 10, -CSP) Cir D2 
-MoveTo MOVE.B ev tMessage+3(A2), D2 
MOVE.W #SysFont,-(SP) SUB . B #'9' D2 
-TextFont Bmi.§ CtlRet 
MOVE.W #'@' -(SP) CMP.B #7,D2 
MOVE.W #applFont,-(SP) BGT.S CtlRet 
-TextFont ANDI.B "$F8,CA3) ; SPCt1Vol 
PEA String! OR.B D2,CA3) 
-DrawStr ing Link A1,8-(csParam+2) 
MOVE.L 835«€16! 19, -CSP) Move.L A1,A8 
-MoveTo Move D2,-CA0) ,csParam 
PEA Str ing2 Assume csCode = csParam-2 
-DrewString Move 82,-CAQ) ;csCode 
MOVE.L 850€16!27,-CSP) Assume ioRefNum = csCode-2 
-MoveTo MOVE .W 8-4 -(AD) ; Sound drvr refnum 
PEA Str ing3 Move.L SP, A0 
-DrewStr ing Control, IMMED 
CLR.W DØ Unik Al 
MOVE.B SpVo1Ct1,DØ LEA SysParam, Ad 
AND .B 32090000111,D0 ; Mask all but low 3 bits MOVEQ ®-1 00 
ADD .B 8'9' DO ; Convert to ASCII -WriteParam 
MOVE. W DØ, -CSP) PEA NumberRect 
-DrewChar -InValRect 
MOVE.L 86516137, -CSP) Bra.S Beep 
-MoveTo 
PEA Str ing4 MyW indow : DC.L ‘j ; DA window ptr 
-DrewString Coords: DC.L 20«€16!10, 35««16! 19, 90€16!27, 
MOVE.L MyW indow, -CSP) ; EndUpdateCMyW indow) 65««16!37 
-EndUpdate WindowRect: DC .W 49,2, 115,213 ; DA window rect 
CLR -(SP) NumberRect: DC.W 38, 175,58, 190 ; DA number 
-SetFontLock rect for invalrect 
LEA Act ivePend, AQ Act ivePend: DC.W ð 
TST.B (AQ) Chars: DC.B 7 
BEQ.S 81 DC.B "9" 
MOVE.W 83,-CSP) DC.W a 
-SysBeep DC.W "- 
LEA ActivePend, AQ DC.B 28, ' 1985 by William P. Steinberg’ 
CLR.B (AQ) DC.B 28, ‘Vers S.B - Free Distribution' 3 
61 BRA CTLReturn DC.B 23*1, 'Current Volume Level s ' 
ASCI IVON: DC.B ð 
; Prime and Status are not used by Desk Accesories. DC.B 21,'Enter New Level (9-7)' 
; These are included "just in case". 
DAPr ime: END 
DAStatus: < , 
CLR.W DO ; Return code : 
RTS E 
RSE 
savePort: DC.L ð ; Application's Grafport 
MyW indow: DC.L 0 ; DA window pointer 
DriverID: DC .W ð ; DA resource id 
DriverType: DC.L ð ; DA resource type 
DriverName: DCB .B 256,0 ; DA resource name 
WindowRect: DC.W 40,2,115,213 ; DA window rectangle 
NumberRect : DC .W 38, 175,50, 190 ; DA number rect. 
jfor invalrect 
ActivePend: DC.B ð 
String!: DC.B 28, ' 1985 by William P. Steinberg’ 
String2: DC.B 28,'Vers 1.0 - Free Distribution’ 
Strings: DC.B 23, Current Volume Level = ' 
String4: DC.B 21,'Enter New Level (0-7)' 
END 
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Assembly Lab 
Macros for McAssembly 


Question: What do you get when you combine the MDS 
assembler, linker, RMaker, PackSyms, and a mini-make 
utility all in one 39K program? 


Answer: McAssembly, from Signature Software. 


This new development system comes complete with 
Apple's Edit, McAssembly, three versions of McBug, and an 
entire disk full of files which were licensed from Apple 
covering everything from the low RAM equates and OS and 
Toolbox equates to interface routines for MacinTalk, 
AppleTalk, Graf3D, and the RAM based serial driver. 


As you can see, McAssembly represents quite a step up 
for me (a veteran MacASM user) in terms of complexity and 
power. I've always ranted against MDS, so why am I using a 
very MDS-like system now? 


First of all, I'm getting into more esoteric climes in 
terms of what I'm trying to do with the Mac. MacASM is 
extremely good at what it promises to do, namely allowing 
the user to easily and quickly develop stand-alone Mac 
applications. 


MacASM lacks the ability to do some things that I now 
find myself wanting to do, such as write desk accessories and 
link object code with code produced by other development 
systems, such as TML Pascal (more about that later). In 
addition, McAssembly maintains two strong advantages that 
MacASM had over MDS - speed and more importantly (n my 
case, anyway), size. I am, after all, a 512K one drive user. 


Let's talk about this new assembler. Edit is by now the 
de facto standard Macintosh editor, so I won't talk about that 
here. 


The best way to talk about McAssembly is menu by 
menu, SO... 


é 1 [3 Assembler Linker Jobs Beeper Transfer 


eS Assemble of 

Link — 9L 
Run job — &J 
Qut — XQ 


mo 
NIIS attt AA d ISIN A A si yA HV YT eet reset et 


Mcfssembly V2. 9 


Signature Software. 
pace in symbol table. 


Fig. 1. The File Menu 
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Asm Link 


Paul F. Snively 
Columbus, IN 
MacTutor Contributing Editor 


The file menu controls execution of the major 
components of McAssembly: the assembler (called McAsm 
when referred to alone), the linker (called McLink when 
referred to alone), and the job controller (no, it's not called 
McJob, it's just the job controller). 


Choosing "Assemble" brings up the standard file dialog 
with a list of all files with an .Asm extension. Selecting a 
file causes McAsm to assemble the file, generating a .REL 
file. 


Choosing "Link" brings up the standard file dialog also, 
but this time it shows files with .Lnk and .Job extensions (I'll 
explain the apparent contradiction a bit later). The .Lnk and, 
in this context, .Job files are linker control files, and choosing 
one causes McLink to try to link together the .REL files that 
it specifies. 


The "Run job" option shows only Job files. Job file 
execution is different depending upon whether the user selected 
the file from "Link" or from "Run job." 


A linker control file is really just a specific kind of job 
control file. All that is in a linker control file is a list of the 
.REL files to be linked (any filenames not ending in .REL 
will have the extension added automatically), segmenting 
information (in the form of $ [ P ] [ L ] lines, where $ is the 
segment break specifier and P and L are optional "Purgeable" 
and "Locked" flags, respectively), filenames of resource files to 
be linked in (preceeded by a "%" - great if you are in the habit 
of creating your resources with ResEdit, for example), and the 
name of the resulting resource file (preceeded by a "/"). 


Job control files, on the other hand, are more powerful, 
but are still simple. They can contain comment lines, which 
start with an asterisk ("*") as well as all of the other kinds of 
lines. That is the only visible difference, and it's not really a 
difference, since Job files can be specified from the "Link" 
menu option. There are, however, other, more subtle 
differences. 


For job control files executed via "Run job," if the 
filenames have no extensions the job controller does not 
assume one. Instead it assumes that the file is to be both 
assembled and linked if at all possible. Files with .REL 
extensions are only linked. 


o The Complete MacTutor, Vol. 2 


If the /filename line is supplied the job controller 
assumes that there needs to be a link phase. Otherwise only 
the assembly phase is executed. 


Now for the interesting part: if a filename in a job 
control file has no extension and there is a / line for the 
resource file specification the job controller will attempt to 
assemble the .Asm file if 1) the .Asm file is presently online 
and there is no corresponding .REL file or 2) the modification 
date on the .Asm file is more recent than the modification date 
on the .REL file (the .REL file is out of date). If the .REL 
file is not out of date, the job controller will not reassemble 
the .Asm file. This intelligent "do I need to assemble or not" 
feature is the mini-make utility that I mentioned. 


Executing a job control file that has a / line as a linker 
control file will behave exactly as any other linker control file - 
there will be no attempt to assemble at all. 


Incidentally, this description of how the job controller 
Works is somewhat at odds with the description in the manual. 
The manual says that the job controller assumes that the 
filenames will have no extension and does not specify what 
happens if that is not the case. Fortunately, files with .REL 
extensions are linked but not assembled - which is how it 
should be, since in some cases (Graf3D.REL, for example) the 
user has the object code but not the source code. 


The "Quit" option, of course, returns to the Finder. 


Copuright|v/Listing to screen — 3D 
286515 by! Listing to file 


«Fr able. 
Errors only listing $C 
Symbol table 
Cross reference 
-PSM file 
DEF all symbols 


Fig. 2. The Assembler Menu 


Figure 2 shows the assembler options menu. As it is 
above the default options are enabled. 


“Object file" enables/disables the generation of the REL 
file. This is useful for just Checking the .Asm file for 
obvious syntactical errors. 


“Listing to printer" selects whether or not to send any 
output to the printer. 
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"Listing to screen" selects the monitor as an output 
device. 


"Listing to file" selects a file with an .LST extension as 
an output device. This is handy for use in Edit to look for the 
lines in error. 


"Errors only listing" toggles between listing only lines 
in error or listing the entire program (subject to the list 
directive value in the source code). 


"Symbol table" toggles the option to display a list of all 
symbols and their values. 


"Cross reference" toggles the ability to display a list of 
what refers to what. All symbols are shown except local 
labels. 


"PSM file" toggles the generation of a file of packed 
symbols for the program being assembled. This probably 
won't be used much; but the assembler's ability to load .PSM 
files will - .PSM files are compact and Speed up assembly 
greatly, because they require no interpretation and are only read 
on the first pass of the assembly. 


"DEF all symbols" toggles the external definition of all 
Symbols in the assembly. The primary purpose of this is to 
have a complete set of symbols to load into McBug, which is 
a symbolic debugger. 


Sound good so far? 


€ File Assembler 


LLL Jobs Beeper Transfer 
Symbol table TATE TSE 


XT pum 
-MAP file output 38M 
Printer output — 30H 
McBug .SYM file x$ 


286515 bytes of free sr 


Fig. 3. The Linker Menu 


The "Symbol table" option allows for the linker to 
display all externally defined symbols in the module. The 
"Symbol table" option for the assembler, incidentally, 
displays all symbols, not just the externally defined ones. 


Don't get too excited about the ".MAP file output." The 
-MAP file that it generates is just a copy of the module map 
displayed by the linker; it bears no relationship to the .MAP 
file generated by the MDS linker. 


"Printer output" prints linker output on the printer as 
well as the screen. 


"McBug .SYM file" toggles the generation of a SYM 
file for the program, which can be loaded into McBug for 
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symbolic referencing. This file format is NOT the same as 
MDS' .MAP format, although the end result is essentially the 
same. One of my future projects is rewriting TMON's User 
Area routines so that they will accept the McAssembly .SYM 
file format. 


A few words about McLink: First of all, no, it is not 
compatible with MDS' linker, Apple's forthcoming linker, or 
any other linker, for that matter. Dave McWherter, the author 
of McAssembly, tells me that his .REL file format is very 
similar to Apple's new one, but he is leery of being the first 
third-party vendor to implement a compatible format - 

especially in light of the fact that Apple's linker hasn't been 
released yet! If you are interested in McAssembly supporting 
Apple's .REL file format, please help me try to convince him. 


You MDS/Consulair linker users needn't feel left out, 
though. Included with the McAssembly system is a utility 
that converts McLink .REL files to MDS format Dave 
admits that he doesn't like the idea; he doesn't like some 
things about the MDS linker, such as the fact that it can't deal 
with BR type instructions (BRA becomes JMP with the MDS 
linker, for example). Also, his utility cannot as of yet convert 
named resources - the name is lost in the conversion. This is 
a minor thing anyway, but he may come up with a version 
that will solve that problem (it revolves around the fact that 
with MDS resource names are symbols whereas with 
McAssembly they are not). The conversion is one way - 
McLink -> MDS Link and not vice-versa. Dave says there 
are some things that his linker does that MDS doesn't and vice- 
versa, which doesn't surprise me. One of the things that 
McLink allows the user to do is to specify an offset from A5 
at which global allocation for the module is to begin. The 
pseudo-op that does this - ASOFF - affects the current module 
and any subsequent modules that don't have ASOFF's of their 
own. Another nice little feature is that if a .REL file contains 
a standard BNDL resource, McLink will automatically set the 
bundle bit on the resulting resource file. More about resources 
in a moment. Also, McLink is blindingly fast compared to 
MDS Link! 


€ File Assembler Linker TUE 


/Stop if Asm error 


No link if Asm error 
McAssembly V2.9 ) 
Copyright (c) 1985 by Signature | Force assemblies 
286515 bytes of free space in syndo 


Fig. 4. The Jobs Menu 


Figure 4 shows the "Jobs" menu with the default options 
enabled. "Stop if Asm error" does exactly that - assembly 
stops if there is an error during the assembly process. 


"No link if Asm error" causes the link phase to be 


bypassed if there were any assembly errors. Both of these 
options, and their rationales, are fairly self-explanatory. 
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"Force assemblies" is the non-obvious one. It causes the 
assembly phase to be executed whether the .REL files are 
current or not. The reason for this is that McAssembly has an 
INCLude pseudo-op which can include other source files. 
What happens if the user changes an included file? The file 
that includes it does not show a new modification date, so the 
job controller ordinarily would not assemble it if a current 
REL file was available. Thanks to the new include file, 
though, the .REL file wasn't really "current" anymore. With 
"Force assemblies," modified include files can be reassembled 
without loading and saving the including source so as to force 
a new modification date. 


é File Assembler Linker Jobs SIKIA 
m: EE tnable Boop 3 
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McAsse 


286515 bytes of free space in symbol table. 


Fig. 5. The Beeper Menu 


The Beeper menu is simple, too. Enabling the beep 
causes McAssembly to beep whenever it encounters the end of 
an assembly, a link, a job, and/or an error. 


286515 bytes of free space in symbol table. 


Fig. 6. The Transfer Menu 


The Transfer menu is pretty straightforward. "Edit" gets 
the user there, and "Other" allows the user to choose any 
online application. Incidentally, Edits Transfer choices are 
"hardwired" as strings in the code, even though the menu itself 
is a resource - bad news. That means that you have to rename 
McAssembly "Asm" on your work disk if you want to be able 
to get there from Edit. Reports are that Apple has contracted 
with Bill Duvall to revise Edit and MDS to be fully HFS 
compatible. Presumably, this means the "hardwired" strings 
would be removed and placed in resources or in some way 
made compatible with the new standard file package. The 
current version of McAssembly is 3.2, which is fully HFS 
compatible on the Mac Plus, except for the MDS Edit 
program problem, which is licensed from Apple and supplied 
on the McAssembly disk. 


That covers all of the menu items and should give you 
some ideas about McAssembly's capabilities. Now let's take a 
look at some of the pseudo-ops that McAssembly places at the 
user's disposal. 
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ASSEC and ASEND are the pseudo-ops that delineate the 
module's global variable area. The pseudo-ops surround a 
collection of DS pseudo-ops and serve to automatically make 
referrences to the labels defined relative to AS. ASSEC and 
ASEND are actually specialized versions of BASE. 


BASE causes one or more labels to be referred to relative 
to a given address register whenever that label appears alone or 
with an additive offset. Incidentally, the first version of the 
assembler that I received had a bug - the additive offset could 
only be a constant, not a label. In other words, if you BASE 
A0,ioFlUsrWds and try to use a line such as CMPL 
fT APPL'ioFIUsrWdsfdType (a real life example from Launch 
Doc), the result is CMP.L #'APPL',$20 instead of CMP.L 
#'APPL',$20(A0). This has been corrected. 


The ASSEC and BASE pseudo-ops make it possible to 
forget about what address register you are dealing with and 
make the use of offset labels (which abound in Mac 
development systems) far more natural. It would not be 
difficult to BASE offsets from A6, for example, giving the 
user a convenient local variable capability. I'll give some 
specific examples of this capability later. 


Some other important pseudo-ops are NOLOC and 
LOCSYM. NOLOC causes local label scoping to behave the 
same way as MDS's. This is helpful, since without it the 
user would have to insert a LOC pseudo-op immediately next 
to every major label in the code to get the same effect. 


LOCSYM allows the user to define the local label 
character. McAssembly normally uses the period as the local 
label specifier, but once again for the sake of MDS 
compatibility LOCSYM "@" can be used to set the local label 
character to be the same as MDS's. 


We've talked about the assembler, the linker, the symbol 
packing function, and the job controller. Now let's take a 
look at resource definition in McAssembly. 


Dave McWherter apparently took a hint from Mainstay 
(the people behind MacASM) with his resource generation. 
The resource compiler is an integral part of the assembler 
itself, and there's no particular reason why you couldn't use the 
assembler strictly as a resource compiler (no code), nor is there 
any reason why you can't put assembler source code in a non- 
CODE resource (meaning that writing desk accessories, new 
INIT resources, new FKEY resources and the like is a snap - 
no more RMaker TYPE DRVR = PROC)! 


McAssembly's resource compiler has two basic modes - 
standard resource compilation and user defined resource 
compilation. 


Standard resources start with the delimiter $$ and have no 
ending delimiter. The supported standard resource types are: 
ALRT, BNDL, CNTL, CURS, DITL, DLOG, FREF, ICON, 
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ICN#, MENU, PAT , PAT#, STR , STR#, and WIND. 


User defined resources start with the delimiter [[ and end 
with the delimiter J]. They can be of any type and can contain 
any valid McAsm data and/or code. 


Any resources defined in McAsm source files must come 
after the program's code. If the user attempts to add code after 
resource definitions errors will result. Furthermore, if you use 
the linker control line "%Filename," where Filename is the 
name of a pure resource file, it must also come after any code 
that is to be linked. The bottom line is that non-CODE 
resources are always last in McAssembly. 


The application signature is a good example of a user 
defined resource. A signature is nothing more than a STR255 
resource by another name. A type is chosen and the TEXT 
pseudo-op is used with the # option, giving the STR255 type 
string, e.g. 


[[ LDOC,0 
TEXT 
]] 


Standard resources look like this: 


# "Launch Doc 1.0" 


$$ FREF,128 
APPL 
0 


Notice that the programmer does not need to know the 
size (word, long, etc.) of the resource item, only its type. A I 
indicates a null string. 


All but a tiny fraction of MDS programs can be 
assembled with McAssembly simply by putting ASSEC and 
ASEND around the globals (and moving them to the front of 
the file, if necessary), adding NOLOC and LOCSYM "@" to 
the front of the code, and converting any resources from 
RMaker format to McAssembly's format (it's easy) and 
appending them to the source file. Assembling and linking 
should generate a working application (or whatever). 


Assembler, editor, linker, 
controller... ah, yes, the debugger! 


resource compiler, job 


McBug is a small, rather elegant little symbolic 
debugger. It's symbolic in that if you (I)nstall an application 
McBug will look for a .SYM file for that application and, if it 
finds one, will allow references to code and data in the 
application by the labels defined in the .SYM file. 


While McBug is certainly not on a par with TMON, it is 


quite capable of holding its own against such debuggers as 
MacsBug. It offers the following features: 


31 


A - ASCII change memory 

B - Set relocation base 

C - Compare memory blocks 
D - Display memory block 

E - Eject diskette 

F - Fill memory block 

G - Go to user program 

H - Hex add/subtract 

| - Install an application 

J - Display trap address 

K - Convert hex to decimal 

L - Locate a hex byte string 

M - Move a memory block 

N - Set display screen size 

P - Peripheral device on/off control 
Q - Quit McBug, execute startup 
R - Read disk sectors 

S - Hex change memory 

T - Trace a user program 

U - Execute a user subroutine 
V - Display user registers 

W - Write disk sectors 

X - Change user registers 

Y - Disassemble user program 
Z - Enter patch assembler 


Not bad for a little (20K) debugger, huh? There are some 
things that aren't implemented as commands that are nice too, 
such as the indirection operator (*). Want to disassemble at 
the current PC? Easy - Y*PC. To make a range that in 
practice extends forever, end a range with the highest possible 
value, which would be all bits high, which translates to -1. 
So, to disassemble from the current PC onwards, Y*PC -1. 


T is nice - I wish other debuggers had it. It somehow 
loads the first segment of the specified program ("I LAUNCH 
DOC" for example) and passes control back to McBug right at 
the JMP instruction which passes control from segment zero 
to segment 1. Before your program can execute its first 
instruction you have control. It beats intercepting  InitGraf, 
which is what I generally find myself doing with TMON. 


The disassembler knows the trap names, so the user is 
spared the agony of looking them up all of the time. The 
patch assembler does, too, but it doesn't know something else 
that can be frustrating - the mask value for the registers on a 
MOVEM instruction. The user must code the register mask 
by hand. Yecch. 


Still and all, it's not a bad little debugger. In fact, I used 
it to debug my McAssembly version of Launch Doc and in so 


doing discovered the additive offset label bug mentioned above. 


So how do I like ità? Have I traded in my MacASM 
wings for McAssembly ones? To whom, if anyone, would I 
recommend this system? 


If you are a serious Mac programmer who wants access to 
most, if not all, of the support files that come with MDS and 
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you want a fast, compact, powerful, inexpensive system that 
is mostly compatible with MDS, McAssembly is your 
system. It is especially an alternative to consider if you are 
writing assembler code libraries to be linked into code 
generated by a high-level language such as TML Pascal. 


I'd like to take this opportunity to thank Dave McWherter 
for providing a copy of the McAssembly system for review 
and for being one of the fastest, most responsive programmers 
that I've known. Not only did he get the original review copy 
to me, he sent one round of upgrades to me on his own 
initiative, wrote MDS Convert basically because I asked him 
to, and fixed the additive offset label problem the same day 
that I told him about it and has sent me that fix, as well as 
other upgrades. If he treats all of his customers the way that 
he treats MacTutor contributing editors, he should have no 
problem selling his system. 


The Bottom Line 


McAssembly strong points: Its small, fast, flexible, 
powerful, relatively inexpensive, and extraordinarily well 
supported. With MDS Convert it's also .REL file compatible 
(to an acceptable extent) with the MDS linker. McAssembly 
comes with a complete application example in source form, as 
well as a very comprehensive application "shell" for I/O 
intensive applications requiring only one large window 
(curiosity and suspicion lead me to disassemble just enough of 
McAssembly itself to reveal what I suspected to be true: 
McAssembly is written in itself and uses the "shell" provided 
with the system - in effect, the shell source is part of the 
McAssembly source)! 

Some new features of version 3.2 is a trap compiler, 
which removes the burden of setting up registers and stack for 
the trap calls. Instead, you specify the trap name, followed by 


. a list of the parameters in the Pascal order, using the 


addressing mode of assembly. The trap called in this manner 
invokes a Macrox which sets up the stack for you and checks 
for the correct number of parameters. For example, if I wanted 
to call the trap to get a new dialog box: 


Old Way: 
CLR.L 
MOVE.W 
CLR.L 
MOVE.L 


-(SP) 
#$100,-(SP) 
-(SP) 

#-1, (SP) 


; returned result 
; Dialog number 
; place on heap 

; put in front 

; do trap call 


. GetNewDialog 


New Way: 
GetNewDialog #$100, $0, #-1 


These parameters are simply values being passed to a 
Macro, and hence any valid source operand expression may be 
used. As you can see, this trap compilation saves a lot of time 
and space setting up all those stack based parameters, and the 
checking for the correct number of parameters is a big help. 
Notice we don't have to do anything about clearing space for 
the returned result. The Macro takes care of that for us, so we 
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can simply pop the result off the stack after the trap call as we 
normally would. 


McAssembly weak points: The terminology can be 
confusing; I had hoped that McAssembly .MAP files were the 
same as MDS .MAP files. Nope. The documentation could 
use a little help. This probably stems from the fact that the 
docs are old; the copy that I received says in the corner of each 
page that it's for V1.3 of the assembler! Using words like 
"relatively" is dangerous; McAssembly is a $90 assembly 
language development system, which is inexpensive relative 
to MDS at full retail, but who pays full retail for anything? 
The first V2.0 copy that I got had some minor bugs, but Dave 
corrected those and got upgrades out so rapidly that I've all but 
forgotten them already. 


[The linker is the last problem remaining as it shares the 
distinction with the Microsoft (Absoft) Fortran linker of not 
being too bright. Why everyone insists on writing their own 
linker when the Consulair smart linker already exists is 
something we fail to comprehend. Rumor has it that the 
Consulair linker, which is downward compatible with the 
MDS ".REL" file format, will be licensed soon to compiler 
authors like TML Pascal, which will make it the standard of 
the industry if it is not already. We would encourage Dave to 
either license this linker or make his conversion utility 
compatible with it so as to allow McAssembly users to be 
able to link McAssembly files with Pascal and C files using 
the Consulair smart linker. In a future issue we will be 
publishing the  Consulair link format to encourage 
standardization of object code file formats. -Ed] 


As promised earlier, I have some macros which make 
writing code for linking into TML Pascal a snap, or, for that 
matter, simulating a Pascal style interface for any reason, such 
as writing new CDEF, MDEF, or WDEF resources, or 
writing I/O completion routines or filter procs for dialog or 
alert boxes. 


First of all, SFBegin is the macro which is used to start a 
Stack frame, which is what you may have when coming into 
the code. 


Long, Word, LongResult, and WordResult are macros 
which define stack frame elements of that length. The Result 
macros are used to make space for the results of functions: 
they are not dropped from the stack upon exit from the 
routine. Struct is used to define a structure of a size other than 
a word or a longword. 


SFEnd is used to terminate the stack frame definition. 


LVBegin is used to start the local variable definitions. 
Local variables are created by your routine at run time. 


LVLong, LVWord, and LVStruct are the element 
definition macros for local variables. 
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LVEnd terminates local variable definition. 


Enter is used to go into a Pascal-like procedure or 
function. 


Exit is used to return from a Pascal-like procedure or 
function. 


Here's the source code for the macro's: 


SFBegin macrox begin a stack frame 
dsec 0 
endm 
SFEnd macrox end a stack frame 
ds.| 2 space for return address 
and stacked a6 
size equ : size of stack frame 
dend 
endm 
Long macrox  &1 a long stack frame item 
ds.l 1 
&1 set .fsize-* 
base a6,&1 
endm 
Word macrox &1 a word stack frame item 
ds.w 1 
&1 set .fsize-* 
base a6,&1 
endm 
LongResult macrox  &1 a long stack frame result 
ds.l 1 
&1 set .fsize-* 
base a6,&1 
.parms set ^ 
endm 
WordResult macrox &1 a word stack frame result 
ds.w 1 
&1 set fsize-* 
base a6,&1 
.parms set i 
endm 
Struct macrox &1,&2 
ds.b &2 
&1 set .fsize-* 
base a6,&1 
endm 
LVBegin macrox begin local var stack frame 
dsec 0 
endm 
LVEnd macrox end a local var stack frame 
|vsize equ T size of local stack frame 
dend 
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endm add.l #.fsize,sp Drop parameters 
endi In either case... 
LVLong macrox &1 a long local variable jmp (a0) To caller 
ds.| 1 else No input or output on stack 
&1 equ -* rts To caller 
base a6,&1 endi 
endm endm 
LVWord macrox &1 a word local variable These macro's (macrox's, really, meaning that they can 
ds.w 1 refer to local labels outside themselves) rely on a very 
&1 equ p interesting pseudo-op: IFDEF. IFDEF is a conditional 
base a6, operator which evaluates to true if the operand (a label) is 
endm defined anywhere in the source code and to false otherwise. It 
exists primarily to allow the creation of exactly the kind of 
roe erg oo «generc OCA, SIAGA NEM macros that you see above: ones that alter their behavior 
&1 equ '* dependent upon whether some other macro has been invoked or 
base  a6,&1 not (for example, Exit's behavior is dependent upon whether 
endm SFEnd, LVEnd, and/or either of the Result macro's have been 
invoked). IFDEF can also be used to ensure that a necessary 
Enter macrox a stack based proc or func symbol file (such as SysEqu.PSM) has been included by 
ifdef |vsize checking a particular system equate and, if IFDEF returns 
Exist? false, using the PRMT pseudo-op to display a message on the 
link a6,#-.\vsize stack space for locals Screen. 
else 
dan ! a6,#0 That about wraps it up - I've spent way too long on this 
pis oor column the way it is. Look in the future for applications, 
ndm desk accessories, and some code libraries for linking into TML 
Pascal - all written with McAssembly. In the meantime, if 
Exit macrox exit a stack based proc or func Youre looking for a good assembly language development 
unlk a6 clear locals from stack system, please give McAssembly your most serious 
ifdef fsize Are there parameters? consideration. McAssembly is available from: 
move.| (sp)+,a0 Get ret address 
ifdef .parms Function as opposed to proc? Signature Software 
add.l #.fsize-.parms,sp If so, remove only 2151 Brown Ave. ee 
input parameters Bensalem, PA 19020 Se 
else If proc (215) 639-8764 (T. ERN 
$89.95 
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Assembly Language Lab 


DA Shows use of Globals and Resources 


Desk Accessories from Assembly 


Desk accessories are a very basic part of the Macintosh 
interface and the development of them need not be a major 
undertaking, if you follow the guidelines in this shell DA. In 
this month's column, I outline how to develop a desk 
accessory using assembly language that illustrates how menu 
items, windows, resources and global Storage can be handled 
within the DA. 


Editor's Notes 


[This program was written and compiled entirely in 
assembly using Consulair's C compiler! That's right. If your 
tired of waiting for Apple to update the MDS assembler 
System to run under HFS without crashing, here is an 
alternative. The Consulair C compiler has a built-in MDS 
assembler that is fully MDS compatible! You simply run it 
like you would the MDS system. Be sure to get the latest 
release 4.53. This release includes version 1.53 of the famous 
Editor. It seems that Consulair went ahead and fixed up their 
own version of the editor, obtaining 1.53, before working 
under contract to bring Apple's editor and MDS system up to 
version 2.0. The result is that Bill's 1.53 editor is more solid 
and more compatible than the current 2.0d1 beta HFS editor 
being distributed by Apple to developers. However, when the 
final 2.0 release becomes released, that will be equivalent to 
the 1.53 Bill is distributing with Mac C version 4.53. Now if 
you understood all that, you should have no trouble with this 
month's column! 

The link file shown at the end of the article is for the 
Mac C linker, which is MDS compatible and it works under 
HFS on the Mac Plus (the MDS one doesn't). You no longer 
need to patch or otherwise coerce the MDS linker into 
launching and finding it's files. The job file shown is also for 
the Mac C Exec and is the same as it would be under the MDS 
exec, only the Mac C version works! You can now invoke the 
job file from the editor and have the assembly, link and 
execution of a program proceed automatically. In this 
example, we execute the DA Mover program after linking so 
we can move the new DA into the system file and test it out. 
This actually works, although the DA Mover comes up 
without knowing what file to open. MacTutor is now offering 
the Consulair Mac C and the linker in our Technical software 
Store for those who want to use it as either an MDS assembler 
replacement or a C system (still a good C system!) or both. 
For those who don't need a C system, we are also offering 
McAssembly which is nearly MDS compatible using a 
conversion utility and the Consulair Linker by itself. -Ed] 
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Example2 .code 


Norman Braskat 
El Toro, Ca 


€ File Edit View Special 


Example 


Example 


Pic. 1: Our DA does windows, menus... 


e Edit View Special ETETE 


| —— Example ——— | 


| Exemple 


This is a example of a MDS desk accessory 
1| which uses a menu. 


By Norman Braskat end MacTutor 


Pic. 2: And alerts! 


General Desk Accessory Information 


To begin, the device manager executes the desk accessory 
as a procedure call of the following format to one of the five 
desk accessory procedures: Open, Control, Prime, Status, and 
Close. 


(DO: ResultCode) := DA Procedure(A0: ParamBlock, A1: 
DCERecord ) 


The 'Open' command is called in response to a 
_OpenDeskAcc toolbox call and in general performs any 
initialization required by the desk accessory. When the user 
selects any DA from the Apple menu, the Finder or 
application calls _OpenDeskAcc. It should allocate any private 
storage required by the desk accessory, stores a handle to it in 
the dCtlStorage field of the DCE record, initializes any local 
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variables, install any interrupt handlers, change interrupt 
vectors, Create any windows, ... ect... 


The 'Close' command is called in response to | DCErecord = 


either CloseDeskAcc toolbox call or by the segment 
launcher to close all the desk accessories, and in 
general it should undo what is done by the Open 
procedure, by releasing all memory used, removing 
any interrupt handlers, restoring any system state... 


( 0) dCtlDriver.Long 
( 4) dCtlFlags.Word 
( 6) dCtlQueue.Word 
( 8) dCtlQHead.Ptr 
(12) dCtlQTail.Ptr 


; A handle to the DA in memory. 
; Control flags * 


ect ... If you must keep state between when the desk 
accessory is closed and later opened, store it in a re- 
locatable block of memory pointed to by the 
dCtlStorage field of the DCE record. In practice, 
'Close' is called by System Click when the user clicks 
the go-away box of a system window belonging to a 
desk accessory, or by the application when the user 
selects "close" in the File menu for an open DA 
window. When that happens, storage used by the DA 
may be released. When a DA menu item 'quit is 
called, the DA can do it's normal close function as 
part of a 'Control' call on the menu event without 
releasing that storage, thus keeping the variables until 
a 'Close' call or another 'Open' call. The code for this 
DA illustrates how this is done. A 'Close' from the 
go-away box of the DA's window will release the 
handle to the storage, but a ‘Close’ from the DA's 
menu will remove the menu and window without 
releasing the storage area, thus preserving variables 
until the next 'Open' call. 

The 'PRIME' and 'STATUS' commands are called in 
response toa. Read, _ Write, or Status trap, and they are not 
used by desk accessories ( I think ). For cleaness sake I use 
empty procedures ( RTS's ). These routines would be used by 
drivers for printers and other I/O type devices. 

The 'Control' command performs most of the work done 
by the desk accessory. It is called in response to one of the 
functions shown in figure 1 and in general will look like a 


Event Description csCode 
accEvent 
accRun 
accCursor 
accMenu 
accUndo 
accCut 
accCopy 
accPaste 
accClear 


; Handle a given event csCode(A0) = 64 
; Handle a periodic action csCode(AO) = 65 
; Change the cursor shape csCode(A0) = 66 
; Handle a menu item csCode(A0) = 67 
; Handle the Undo cmd csCode(A0) = 68 
; Handle the Cut cmd csCode(A0) = 70 
; Handle the Copy cmd csCode(AO) = 71 
; Handle the Paste cmd csCode(AO0) = 72 
; Handle the Clear cmd csCode(A0) = 73 


FIGURE 1 csCode ENCODING FOR REQUESTED ACTIO 


case statement which decides what to do, and then does the 
required action. All events are handled as ‘Control’ calls and in 
general, any action during an active DA's life is handled as a 
'Control' call. 

As figure 1 shows, the AO and A1 pointers allow access 
to all the information required to determine exactly what 
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(16) dCtlPosition.Long 
(20) dCtlStorage.Handle ; Handle to DA's storage area in memory 
(24) dCtlRefNum.Word 
(26) dCtlCurTicks.Long 
(30) dCtlWindow.Ptr 
(34) dCtlDelay.Word 
(36) dCtlEMask.Word 
(38) dCtlMenu.Word 


FIGURE 2. 


; Byte offset used by Read and Write 


: DA's RefNum 

; Current interval count in ticks 
: Pointer to DA's Window 

: Interval count in ticks ** 

: Event mask ** 

: DA's Menu ID ** 


* The upper byte is copyed from the flag byte of the DA's header. 
** These fields are copyed from the DA's header. 


DCE Record 


operations are requested and to execute them. The AO register 
contains the pointer to the parameter block (see figure 3) while 
the A1 register contains the pointer to the DCE record (see 
figure 2). And for DA's, the result code returned in DO should 
always be zero. 


Device Control Entry Record 


The DCE record (see figure 2 ) contains some 
information taken from the DA's header, the always present 
queing infromation, a handle to the DA's storage area, a 
pointer to the DA's window, and some other control 
information. Most desk accessorys are only interested in the 
'dCtlStorage', 'dCtlIRefNum', and the 'dCtIWindow' fields, and 
in general the rest of the record is only used by drivers and the 
device manager. Upon entry, A1 holds a pointer to the DCE 
record and great care must be taken to see that this pointer is 
preserved throughout the DA. Many DA errors are due to this 
pointer being clobbered by a trap call. 

The dCtlStorage handle allows the desk accessory to have 
its own global memory area seperate from the stack. The DA 
cannot use register A5 since that is used by the underlying 
application for it's globals. Care must be taken to unlock and 
deallocate any memory the DA may have when it is closed, 
since the device manager will not do this for you. 


IO Parameter Block 


The Parameter block pointed to by AO (see figure 3) 
contains the action code and any data passed by the device 
manager. The csCode contains the action code and will be a 
value from 64 to 73. The parameter block will contain any 
data passed. Menu actions will pass the MenuID (28) 
followed by the MenuItemNum (30). 
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PBBlock = 


( 0) qLinkPtr 


( 4) qType.Word 

( 6) ioTrap.Word 

( 8) ioCmdAddr.Ptr 
(12) ioCompletion.Ptr 
(16) ioResult. Word 
(20) ioNamePtr.Ptr 
(24) ioRefNum.Word 
(26) csCode.Word 
(28) csPram.Block 


FIGURE 3. IO PARAMETER BLOCK 


Support Resources 


To use the 'DA MOVER' program for installing your 
desk accessory it will be necessary to make the resource ID's 
for alerts, dialogues, pictures, ect.. be a function of the DA's 
number. The equation used is: 


ResurceID := (( DA's number ) x #32) + 8$FFFFCOO0 + 
index 
and 


( DA's number ) := (- (DA's RefNum) - #1) 


This would have the resources for DA (#12) Starting at 
#-16000, with a maximum of #32. The assembler makes it a 
bit difficult to code this 16-bit 2's complement number, but I 
found that using a decimal value of 49536 in the resource 
header produces the desired equivalent of -16000. (See the 
resource section of the listing). Also, the DA name should 
have a null ($0) byte as the first character of the name, but the 
assembler won't let you do this in the resource header. The 
resource editor can be used to do this, but as it turns out, the 
Font/DA mover does it for you when it installs the DA. 


Desk Accessory Header Format 


The first 9 words of the desk accessory constitute a header 
and is followed by the DA's title string. Figure 4 defines the 
structure of the header block. With this information, we can 
Start writting our desk accessory. 

In this example, I have coded simple open, control and 
Close procedures to check for and allocate global memory 
storage via A4. Once this is done, a central ‘launch’ routine is 
called that provides a single interface to the DA's major code 
blocks for open, control and close. The launch routine saves 
State and calls the three DA routines which then decode the 
action parameters and perform the necessary actions. When 
adapting this shell to your own needs, you simply place your 
open code, control code and close code in the three routines 
called by launch: OpenDA, MainDA and CloseDA. 


© The Complete MacTutor, Vol. 2 


Header = 


Control flags byte 
Version byte 
Service interval word 
Event mask word 
MenulD word 
Open - Header word 
Prime - Header word 
Control - Header word 
Status - Header word 
Close - Header word 
Title string 
Control flags = 
bit 7 Not used ? 
bit 6 Memory lock requested 
bit 5 Enable periodic execuition 
bit 4 Call before stack reinitialized 
bit 3 Enable statusexecuition 
bit 2 Enable control execuition 
bit 1 Enable writeexecuition 
bit O Enable read execuition 
FIGURE 4 DESK ACCESSORY HEADER 


—c—-—_— eee 


; Asm language desk accessory. 

; © March 1986 by Norman Braskat 

; for MacTutor. 

; Extended to windows March 26, 1986 
; by David Smith 


RESOURCE 'DRVR' 12 ‘EXAMPLE DA‘ 


INCLUDE — MacTraps.D 

. trap -DeBug $A9FF 

StorageSize EQU 6 

; Globals relative to A4 (dCtlStorage] 
MenuHandle EQU Ü ; long] 
ResourceBase EQU 4 ; word] 
csCode EQU 26 ; control/status [word] 
csParam EQU 28 , parameters [29 bytes] 
MenuItemNum EQU 30 

; DCE item list 

dCt1Driver EQU "| 

dCtlFlag EQU 4 

dCtTQuer EQU 6 

dCtlHead EQU 8 

dCtlTail EQU 12 
dCtlPosition EQU 16 
dCtlStorage EQU 20 

dCt 1Ref Num EQU 24 
dCt1CurTicks EQU 26 

dCt1Window EQU 30 

dCtlDelay EQU 34 

dCtlMask EQU 36 

dCt Menu EQU 38 


; Toolbox equates 


WindowKind EQU $6C — ;offset from wind. rec. 


; Event parameter block equates from SysEqu 
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ev tNum EQU ð ; event [word] 

ev tMessage EQU 2 ; msg [long] 

evtTicks EQU 6 ; TICKS [long] 

evtMouse EQU 10 ; mouse pos. [long] 

evtMeta EQU 14 ; meta key flags [byte] 
evtMBut EQU 15 ; mouse button [byte] 
JI0Done EQU $8FC ; I0Done entry [pointer] 


wee We We We We We We We We 


we 


MACRO 


MACRO 


MACRO 


MACRO 


MACRO 


MACRO 


; The following defines the desk accessorys resource header. 


ENTRY: 
DELAY: 
EventMask: 
MenuID: 


MenuTitle: 


DC.W $0400 ; control flags. 
DC.W $0000 ; Service interval 
DC.W $0040 ; Event mask. 

DC.W $FEA1 ; DA MenuID's 

DC.W Open - Entry  ; Offset to Open 
DC.W Prime - Entry ; Offset to Prime 
DC.W Control - Entry; Offset to Control 
DC.W Stetus - Entry ; Offset to Status 
DC.W Close - Entry ; Offset to Close 
DC.B 7 j length byte 

DC.B ‘Example’ ; menu title 


align 2 


Register Usage 

AQ = ParamBlock ptr, 

A1 = DCE ptr, 

A2 = evt table ptr from csParamC(Ad), 

A3 = working DCE ptr Cafter launch) 

A4 = globals (referenced to dctlstorage?, 
A5 = application globals (not used), 

A6 = frame ptr, 

AT = stack ptr. 


Useful Macros 


PUSH value = 

‘ha (value), -(A7) 
PUSH.L value z 

rains (value), -CA7) 

POP value = 

ri (A7)+, (value) 

POP .L value = 

‘ides (A7)+, (value) 
EnableItem value= 
MOVE.L MenuHandleCA4), -CATO 
MOVE (value), -CA7) 
Coo 

DisableItem value= 
MOVE.L MenuHandle(A4), -CA7) 
MOVE (value), -CA7) 


pR 


; The menu name string 


MenuList: DC.B 18 


Wbounds: 


; List in bytes 


DC.B ‘About; ' ; Iten *1 title 
DC.B 'Beep; ' ; Item #2 title 
DC.B € ; Item *3 title 
DC.B ‘Close; ' ; Item #4 title 


DC.W 108, 100, 140,300 ; window bounds 


; Desk accessorys don't use Prime and Status 
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Prime: 
Status: 


RTS 
RTS 


The Open procedure allacates the storage area 
builds the DA's menu list, and opens windows. 
Don't allocate a memory area if one is 
already allocated. 


The notation I use to document my code is a 
psudo Alogal followed by the assembly code. 


Open 

BEGAN 

save users port (GetPort) 

IF € dCtiStorage = #9 ) 
dCt Storage 

Launch( OpenDA ) 

restore users port (SetPort) 

END 


Wwe We We We We We Be We We We We We We We We 


; Seve the application's port because 
; the ROM doesn't do it for us on Open. 


:= NewHandle( StorageSize, Clear ) 


push. ] Al 


=. & 


Seve A1 (DCE ptr.) 


subq. | "4 SP ; make room for the port 
move. ] SP,-(SP) ; push a pointer to it 
-GetPort ; get it, on top of stack 
POP.L D6 ; Seve port in D6 
pop.L Al ; restore DCE ptr. 
TST.L dCtlStorage(A1) ; Storage allocated? 
BNE Open. ; yes, skip allocation 
PUSH.L Ag ; no, Save AQ from wipe-out 
MOVE StorageSize,DÜ ; storage handle to A0 
-NewHandle, Clear ; get storege, zero block. 
MOVE.L A9, dCtiStorageCAl) ; handle in the DCE 
POP.L A0 ; Restore A8 register 
Open. 2: 
PEA OpenDA ; pointer to OpenDA proc 
JSR Launch ; passed to launch code. 
push. 1 D6 ; push users port 
-SetPort ; restore users port 
CLR.L DØ ; clear DØ for DA return 
RTS ; Return to desk manager 


; The Control procedure handles most of 

; the work done by the desk accessory. 

; If a memory area is not already allocated 
; we should never have been called, so just 
; return to the device manager. Otherwise, 
; pass the MainDA procedure to the launch 

; code and then do i 


; The Close procedure removes the 
; end in general cleans up after 
; Open and control procedures. 

; If a memory area is not already 
; allocated there is nothing to c 


O The Comple 


; Control 
, BEGAN 
; IF CdCtiStorage 250) 
; Launch(MainDA) 
; JMP to IODone 
; END 
Control: 
TST.L dCtiStorage(Al) ; storage area? 
BEQ Control. 9 ; No, so exit... 
PEA MainDA ; yes, pass MainDa function 
JSR Launch ; to the launch code. 
Control_9: ^ 
CLR.L DØ ; Clear DØ for return 
MOVE.L JIODone, -CSP) ; System IODone entry point 
RTS ; return to IODone. 


DA's menu 
the 


lean 
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; Up, SO return to the device manager. 

; Otherwise, pass the CloseDA procedure 

; to the launch code and then do it. 

; After the returning from the lanch code, 

; deallocate the handle to storage area 

, and return to the device manager. Typically, 
; close is only called by the system 

; when the go-away box of a window is clicked. 


: Close 


b 
; BEGAN 
, save users port 
, IF C dCtiStorage ##9 ) 
j LeunchC CloseDA ) 
; DeleteStorageArea 
, restore users port 
; END 
Close: 
push. 1 A1 ; save DCE ptr. 


ə 
subq. 1 84 SP » make room for the port 
move. | SP, -CSP) ; push a pointer to it 
-GetPort ; get it, on top of stack 
pop.1 D6 ; get port in D6 

pop. 1 Al ; restore DCE ptr. 


TST.L dCtlStorege(A1) ; Storage area allocated? 


BEQ Close.0 ; no so exit... 

PEA CloseDA ; yes, prepare for close 

JSR Launch ; do close stuff... 

MOVE.L dCtIStorageCA1), Ag ; get storage handle 

clr.1 dCtlStorage(CA1) ; Clear handle (must do!) 

-DisposHandle ; Deallocate handle 
Close_9 

push. ] D6 ; push port 

-SetPort ; restore users port 

CLR.L DØ ; clear DØ for return 

RTS ; and return to desk manager. 


; The Launch proc creates the environment 
; for the execuition of the DA's code. 


; Leunch € &Procedure ) 


: BEGAN 

; SeveState 

; M:s DCE ptr 

, A4 := [HLockC dCtiStorage ) ) 

; Procedure 

j WMUnLockC dCtlStorage ) 

; RestoreState 

; END 

Launch: 
LINK A6, ttg ; Link in. 
MOVEM.L D1-D7/A0-46,-(A72; Save register state 
PUSH.L A1 ; Save pointer to the DCE rec 
PUSH.L A0 ; Save pointer to param block 
MOVE.L A1, A3 ; Move DCE to safe register. 
MOVE.L dCtIStorage(A3), AØ — ; get dCtlStorage handle 
-HLock ; lock handle 
MOVE.L CAB), A4 ; M is used as the global reg 
POP.L AQ ; Restore param block ptr. 
MOVE.L 8CA6),A2 , get function off A6 stack 
JSR (A2) ; Call the passed procedure. 
POP.L A1 , restore DCE ptr. 
MOVE.L dCtiStorege(A1), AD  ; get storage handle 
-HUnLock ; Unlock handle 
MOVEM.L CA7)+, D1-D7/A0-A6 ; restore register state. 
UNLK A6 ; Link out. 
POP .L A0 ; get return address 
ADD.L 84, AT , pop off launch param 
JMP (A0) ; return to caller 
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"OpenDA' routine installs the menu list 

in the system bar, refreshes the menu 

item states, and opens a window. In general, 
this is where the code that must be 
execuited on opening is placed. 


;OpenDA (called by launch) 


ResourceBase :- #$FFFFCØØØ or (#32 x (-RefNum -1)) 
IF € MenuHandle 2 *g ) 

MenuHandle := NewMenuC MenuID, &MenuTitle ) 
AppendMenuC MenuHandle, &MenuList ) 
InsertMenuC MenuHandle, #9 ) 
DrewMenuBar 
RefreshMenu 

IF € Windowptr # #0 ) 
Windowptr := NewWindowC .. ) 
Seve windowptr in ctl block 
set window kind to system window 


END 

OpenDA: 
MOVE dCtlRefNunCA3),D0 ; DA mover requires 
NEC DO ; Support resources ID for a DA to be 
SUBQ #1, DØ ; function of the DA ref. number. Use 
ASL #5, DØ ; value in ResourceBase(A4) for 
OR "$C000 ,D0 ; your supporting resources. 
MOVE DØ, ResourceBase(CA4) ,Save resource ID 
MOVE.L MenuHandleCA4),D0 ; menu handle? 
BNE OpenDA.9 ; yes, don't add another. 
CLR.L -(AT) ; no, clear space 
PUSH MenuID ; Push the MenuID 
PEA MenuTitle ; Push menu title ptr 
-NewMenu ; make new menu 
MOVE.L CA7), MenuHandleCA4) , save menu handle. 
PEA MenuList ; Push pointer to item list. 
-AppendMenu ; Append the menu 
PUSH.L MenuHandleCA4) ; Push the handle 
CLR -(AT) — ; zero for append last menu. 
-InsertMenu; insert the menu in the bar. 
-DrawMenuBar ; Redraw the menu bar. 


s 


we We Ve 


j 
) 
" 
P 
" 


Now open a window 


tst.1 DCtIWindowCA3) — ; window open? 

bne.s OpenDA. ; yes, skip this 

clr. -(SP) ; room for window pointer 
clr.1 -(SP) ; window on the heap 

pea Wbounds ; pointer to boundsRect 
pea MenuTitle , pointer to title 

clr.w -CSP) ; false for visible 

move .w 80 ,-(SP) ; Standard window type 
move. 1 8-1,-(SP) ; window in front 

move.w "$0100, -CSP) ; true for goAway box 
clr.] -(SP) ; refCon is Ø 

-NewWindow ; do the allocation 

move. 1 (SP +, Ad » pop windowPtr off stack 


Save the window pointer away in the DCE for future use. 
The system also uses the DCtlWindow field of the DCE 
for setting up update events to system windows etc. 


move. | AD ,DCtIWindowC(A3); save window ptr in DCE 
move.w DCtlRefNunCA3), WindowK ind( A0) 


All drivers, including ornaments, have a negative refnum. 
The only way an application can know what the refnum 

of this ornament is is by getting it from the 

WindowKind field. Applications must have the 

refnum to do CloseDeskAcc(). 


OpenDA. 9: 


JSR RefreshMenu ; Refresh the menu states. 
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RTS ; Return 


The’ RefreshMenu' routine, updates the display 
state of the menu items in the DA's menu. 
Enabled/Disabled, Checked/UnChecked, ect. 


Note... The menu manager will not act on a disabled item. 


RefreshMenu 
BEGAN 
IF € MenuHandle # 80 ) 
EnableItem( #1 ) 
EnableItem( #2 ) 
DisebleItemC 83 ) 
EnableItemC #4 ) 


we We We We We We We We 


END 

RefreshMenu: 
TST.L MenuHandleCA4) must be & menu handle s 
BEQ RefreshMenu.£ to acces the menu. 


EnebleItem #1 
EnableItem #2 
DisableItem#3 
EnebleItem %4 

RefreshMenu.£: 
RTS 


Enable menu item 81 
Enable menu item 82 
Disable menu item 83 
Enable menu item 84 


we We We We We We 


; This routine will delete the DA's menu, and window 
; and redraw the menu bar. Place your close functions here. 


; CloseDA 
; BEGAN 
IF € MenuHandle # "9 ) 


IF € WindowPointer * #@ ) 


4 

2 

é 

é 

é 

; DrawMenuBar 
; END 

C 


loseDA: 
TST.L MenuHandleCA4) 
BEQ CloseDA. 0 
PUSH MenuID 
-DeleteMenu; Delete menu. 
PUSH.L MenuHandleCA4) 


Ccalled by launch) 
DeleteMenuC MenuID ) 
DisposeMenu( MenuHandle ) 


Delete dCtlWindowC DCE Ptr ) 
DisposeWindow( WindowPointer ) 


; If the menu handle is zero, 
; there is nothing to delete. 


-DisposMenu; Dispose of the menu 


CLR.L MenuHandleCA4) 
; close window 


TST.L DCtlWindowCA3) 


BEQ CloseDA. 0 
move. | DCtl1WindowCA3), -CSP) 
clr.1 DCt1WindowCA3) 
-DisposWindow 

CloseDA. 0: 
-DrawMenuBar 


; Zero the handle 


; no window to delete 

; push the window ptr 
; clear window ptr 

; dispose window 


; Redrew the bar. 


; The MainDA routine looks like a case statement 
; which determines the necessary action end does it. 
; Control requests come here for all events, ect. 


MainDA 
BEGAN 
CASE of csCODE 

64 : 


we We We We We 


65 : 
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(called by launch) 


AccEvent 
AccRun 


; 66 : AccCursor 
F 67 : AccMenu 
$ 68 : AccUndo 
; 69 : NotUsed 
! 10 : AccCut 
` T1 : AccCopy 
j T2 : AccPeste 
; 73 : AccClear 
; ELSE : Nop 
; END 
; AccMenu 
; BEGAN 
; CASE of MenuItemNum 
; 1: About; HiliteMenu; RefreshMenu; 
; 2: Beep; HiliteMenu; RefreshMenu; 
: 4: CloseDA; 
; ELSE : Nop; 
; END 
MainDA: 
MOVE csCodeCA2), DØ 
SUB $64, DØ 
ASL "2, DØ 
LEA JumpTable, A2 
JMP (A2,D0 .W) ; Case of CcsCodeCA0)-3164) 
JumpTable: 
JMP AccEvent 
JMP AccRun 
JMP AccCursor 
JMP AccMenu 
JMP AccUndo 
JMP NotUsed 
JMP AccCut 
JMP AccCopy 
JMP AccPaste 
JMP AccC lear 
AccRun : RTS , these here are not used 
AccCursor : RTS 
AccUndo: RTS 
NotUsed: RTS 
AccCut : RTS 
AccCopy: RTS 
AccPaste: RTS 
AccClear: RTS 
AccEvent: 
move. | CSPeremCA2),A2 ; get the event pointer 
move .W EvtNum(A2), DØ ; get the event number 
; event jump table goes here 
Subq "6 D0 ; is it an update? 
beq.s Update ; if so, go handle it 
RTS 
Update: 
move. | EvtMessage(A2),-CSP); push window ptr 
-BeginUpdate ; begin the update 
move.1 EvtMessage(A2),-(SP); push window ptr 
-SetPort ; Set the port to our 
port 
bsr DrewWindow ; drew the window 
nove.1 EvtMessage(A2),-C(SP); window ptr last time 
-EndUpdate ; end the update 
RTS 
4 
DrawWindow: 
PUSH.L Ad ; save Ad 
move .W "5 -(SP) ; move over 5 horizontal 
move.w 815, -CSP) ; and 15 vertical 
-MoveTo ; do the move 
lea MenuTitle, Ag 
move. 1 Ad, -CSP) ; pointer to the string 
_DrawStr ing 
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POP.L Ag ; restore AQ 


rts ; done drawing 
uu ——— RN 
AccMenu: 
MOVE MenuItemNumCA2), DØ 
CMP #1, DØ 
BEQ MenuItem1 
CMP "2, DØ 
BEQ MenuItem2 
CMP "4, DØ 
BEQ MenuItem4 
RTS 
MenuItem1: 
JSR About 
BRA Exit 
MenuItem2: 
JSR Beep 
BRA Exit 
Menul tem4: 
JSR CloseDA 
RTS 
Exit: 
CLR -(AT) ; UnHilite menu 
-HiliteMenu 
JSR RefreshMenu ; Refresh menu item states 
RTS 
About: 
CLR -CAT) 
PUSH ResourceBase(A4) 
CLR.L -(AT) 
Alert 
POP DØ ,alert parameter 
RTS 
Beep: 
PUSH #15 ; Beep... 
_SysBeep 
RTS 
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, resource ID numbers must be negative functions of 
; DA ref. number. Note that 49536 = 0000 C180 

; which the assembler converts to -16000. Note that 
; the assembler converts a 16-bit negative such 

, 8s -16000 to a 32-bit field, ie FFFF C180, 

; which doesn't work. 

RESOURCE 'DITL' 49536 ‘EXAMPLE DITL' 


DC .W Ü 
DC.L g 
DC.W ø 
DC. W ð 
DC. W 129 
DC. W 309 
DC.B 8 
DC.B 102 
DC.B 13, 13 
DC.B This is a example of a MDS desk accessory 
which uses a menu. ' 
DC.B 13, 13 
DC.B i By Norman Braskat and MacTutor ' 
„ALIGN 2 
RESOURCE 'ALRT' 49536 ‘EXAMPLE ALRT’ 
DC .W $QO7A 
DC .W $0064 
DC.W $00FA 
DC.W $0186 
DC.W $C 140 
DC.W $4444 
„ALIGN 2 
END 


; Link file for exenple2 DA 


] 
/Resources 
Example2 
/output Example2.code 
/Type 'DFIL' 'DMOV' 

$ 
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Ask Professor Mac 


Reader's Technical Questions 


Desk Accessories and JIODone 

Q. Jan Eugenides sent me a question about how the Control 
routine of a desk accessory should return: via an RTS 
instruction or via a JMP through JIODone? This turns out to 
be a somewhat complex issue; the following discussion is 
based on answers from my most trusted authority, the ROM, 
and insights provided by Lew Rollins and Jon Hueras via the 
CompuServe Mac Developers SIG. 


A. Inside Macintosh says that the Control routine of a 


driver should return to the ROM's IODone routine -- to the 
address contained in the system global variable JIODone. 
When jumping through JIODone, register Al must contain 
the address of the driver's Device Control Entry (DCE); 
otherwise, no registers need to be preserved by the Control 
routine. Generally, any queued request to a driver must return 
to IODone so that the system won't hang waiting for 
completion of the request. 

If a driver doesn't need to be locked in the heap when it is 
not executing, it has the dRAMBased bit in the DCE set and 
the dNeedLock bit clear. Note that a driver is always locked 
before it is entered, so self-locking by a driver is superfluous. 
The dNeedLock bit specifies whether the driver needs to be 
locked when it is not executing. If dNeedLock is clear, 
IODone will unlock the driver and the DCE. 

For queued I/O requests, IODone removes the completed 
request from the queue and dequeues the next pending request, 
if any, for execution. However, Desk Accessory (DA) Control 
requests are not queued (they have the noQueue bit set in the 
Conrol trap word) except for the case of the "goodbye kiss" 
(csCode = -1) call that is issued if the dNeedGoodbye bit is set 
in the driver header. 

But... the IODone routine in the 64K ROM has a bug 
(fixed in the 128K ROM). In order to determine if the request 
was a queued one, it looks at the noQueue (.IMMED) bit in 
the trap word in the queue element pointed to by the 
dCtlQueue field of the DCE. Problem is, if the request was 
not a queued one, then it's not in the queue to be examined! 
Since DA Control calls (except for a "goodbye kiss") are not 
queued, IODone will be using a Nil pointer in the dCtlQueue 
field and will examine the word at offset ioTrap (offset 6) from 
address zero, i.e., address 00000006. As luck would have it, 
usually the noQueue bit happens to be set at that irrelevant 
location, and IODone doesnt't try to remove the nonexistent 
queue element — so the bug doesn't usually bite. But it's dicey 
for a DA to depend on that happenstance. 

A further complication for some DAs is that their 
Control routines may be reentrant. Consider the case of a DA 
that has the dNeedTime bit set in its header because it wants to 
be called periodically. Suppose this DA's Control routine 
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calls ModalDialog (possibly indirectly via SFGet/PutFile or 
Alert). ModalDialog calls SystemTask, which in turn may 
issue a periodic Control call to the DA. If the DA is always 
unlocked at Control exit (either explicitly by itself or by 
IODone), then the periodic call will at exit unlock the 
DA/DCE, and when ModalDialog returns the hapless DA will 
find itself "mysteriously" unlocked with perhaps disastrous 
results. If you share Jon Heuras's "sheer paranoia" about 
reentrancy, you can use his technique of clearing the 
dCtlEnable bit in the DCE at entrance to Control, and setting 
it again at exit -- this avoids reentrant Control calls. 

Ok, so those are the facts -- what does it all mean? I 
would suggest the following approach. It assumes that the 
DA does not need itself nor its DCE to be locked while the 
DA is not executing; and it permits reentrance. There are few 
cases when a DA must be locked when not executing, and it is 
impolite to the host application to have unnecessarily-locked 
blocks in the heap. 

Allocate a word -- or to be safe, a longword -- in the DAs 
private storage to be used as a Control entrance counter. Clear 
this counter in the Open routine. At entrance to the Control 
routine, increment the counter. Then the Control exit logic 
would look like this: 

JAO points to the request parameter block 
;M points to the DCE 


j the following 4 lines can be omitted if dNeedGoodbye is clear 
;- otherwise we assume private storage has beed disposed of 
B 


tst 8SnoQueueBit-8, ioTrapCAQ) ;queued request? 
Beq.S eo jno 
Move .L JI0Done, Að ,yes, it's "Goodbye"... 
Jmp (A0) jso return to I0Done 
ed M Move.L — dCtlStorage(A12,A0 ;get storage handle 
Move.L CAB), A2 ; dereference 
SubQ.L %1,EntranceCount(A2) — ;decrement counter 
Bne.S 1 ;br if reentered 
-HUnlock ;unlock storage 
Move.L A1,A0 ;DCE pointer 
-RecoverHandle ;UCE handle 
-HUnlock ;unlock DCE 
Lea Driver, AS ,addr of this DRVR 
-RecoverHandle ;hendle to ourself 
-HUnlock ;unlock ourself 
61 Rts ;bypass IODone 


Scamble Well, Please 
Q. Dr. David T. Linker of Trondheim, Norway, writes, “I 
was encouraged by your comment on 'dumb' questions [I 
solicited them! --SB]. Why do Macintosh debuggers offer to 
scramble the heap? I use the heap ... but I can't think of a 
reason why I would want to scramble it. It seems that this 
would be undesireable, kind of like ‘scramble variables." 


A. "Rearrange" would be a more accurate word for the 
function offered by the debuggers. Scrambling the heap means 
to move relocateable blocks around; if your code at some point 
depends on the incorrect assumption that a given block is 
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locked (won't move), then scrambling the heap may help to 
reveal that bug. After the scramble, the program won't find 
what it expects to find at what it thinks is the address of the 
block, and will probably behave differently than it would 
without the scrambling. 

Such a buggy program may have seemed to be healthy 
only because, by luck, the block has not moved; but in some 
circumstances that testing has not yet encountered, the block 
will move, and the program will crash or otherwise 
misbehave. If your program can survive a heap scramble on 
any trap which might rearrange the heap, then you can have 
some confidence that it is not making incorrect assumptions 
about blocks being immobile. 

Application Icon 
Q. This and the following question were submitted by 
L. Tannenbaum of Long Beach, Calif. "How do I get the 
Finder to use the 'generic' icon for an application? What info 
do I include or exclude in the resource file?" 


A. This is an unusual question — most often, people want 


to know how to give their application a custom icon. To get 

the generic "hand-on-diamond" icon on the Finder desktop, all 

you need do is specify APPL for the type of the application 

file. Begin your RMaker input file with: 

Name Of My Application File 

APPLMYAP 

This examples uses MYAP as the signature of the application. 
Moving Pictures 

Q. How do I get a "PICT," say one I drew in MacPaint, into 

a resource file? I have RMaker (with no documentation) and 

REdit (not ResEdit). 


Á. Use RMaker to create a dummy PICT resource in the 


target resource file: 
TYPE PICT = GNRL ;; define a "new" type via GNRL 
,128 3; resource ID 

I 3; integers follow 
0000 ;; dummy rectangle coordinates 

In MacPaint, cut your picture and paste it into the 
Scrapbook. Now run REdit and open your resource file and 
the PICT resource type. You'll see PICT 128 represented by 
an icon. Open the Scrapbook, cut the picture from it, select 
the PICT 128 icon, and paste. (P.S. ResEdit is more 
powerful than REdit; ResEdit lets you create resources as well 
as modify them. ResEdit 1.0d5 is available on the MacTutor 
Utility disk and source code disk #6. ] 

AutoWatch 

Its a service to the user for an application to display a 
wristwatch cursor whenever the application is busy and not in 
the mood for user input. But it's something of a nuisance for 
the programmer to explicitly change the cursor before and after 
each time-consuming operation; besides, sometimes it's not 
easy to know a priori that an operation will be time- 
consuming. 
~ I saw a message from Larry Rosenstein of Apple on one 
of the networks in which he outlined a scheme for automating 
changing of the cursor to a watch and back. The basic idea is 
to install both a vertical-blanking (VBL) interrupt task and a 
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hook into GetNextEvent. If GetNextEvent has not been called 
for some pre-defined period of time, then the application is 
deemed to be "busy" and the cursor is changed to a watch; this 
is done by the VBL task. 

The system's VBL interrupt handler checks each element 
in a VBL queue each 60th of a second, decrementing a counter 
value in the queue element. If the counter decrements to zero, 
a task associated with that VBL queue element is executed. 
Then -- unless the VBL task reinitialized the counter to a non- 
zero value -- the element is removed from the queue. For 
more information, see the Vertical Retrace Manager chapter of 
Inside Macintosh. 

Suppose we want a watch cursor to be displayed 
whenever half a second passes with no calls to GetNextEvent. 
What we do is install a VBL task with a value of 30 (30/60 of 
a second) in the associated VBL queue element counter field. 
We also revector the GetNextEvent trap to a piece of code 
which restores the counter in the VBL queue element to 30 
(and then does normal GetNextEvent processing). If 
GetNextEvent is called at least once every half second, the 
VBL task will never be executed, because the VBL queue 
element's counter will never get decremented to zero. But if 
half a second elapses with no calls to GetNextEvent, the VBL 
task will be executed. 

‘When the VBL task is executed, it examines a global flag 
which indicates whether the cursor has already been changed to 
a watch. If the flag is false, the task saves the current Cursor, 
changes the screen cursor to a watch, and sets the flag. Then 
it restores the counter field in the VBL queue element so that 
the element will not be dequeued. 

The GetNextEvent hook code restores the VBL task's 
timer value, and, if the VBL task changed the cursor from a 
non-watch to a watch (indicated by the global flag set by the 
VBL task), restores the original cursor. 

In simplest terms, every time GetNextEvent is called it 
says to the Vertical Retrace Manager, "Whoa! The application 
is not busy! Restart your countdown." The Vertical Retrace 
Manager, each 60th of a second, decrements the counter; if it 
has reached zero, that means GetNextEvent has not been called 
since the countdown last started, implying a busy application 
which needs a watch cursor: the VBL task is executed and 
changes the cursor. 

There are a couple of minor complications. The 
GetNextEvent hook code cannot just do an InitCursor (which 
makes the cursor an arrow), because the pre-watch cursor may 
not have been an arrow. But neither can it blindly restore 
whatever cursor the VBL task saved. Consider this example: 
the application calls DIBadMount to initialize a disk. 
DIBadMount changes the cursor to a watch as it starts to 
format the disk. Shortly thereafter, the VBL task countdown 
reaches zero, and the VBL task saves the current cursor (a 
watch!) and sets the cursor to a watch — superfluous, but no 
harm done. When the disk format completes, DIBadMount 
does an InitCursor, and returns to the application. The 
application calls GetNextEvent. Now our GetNextEvent hook 
sees the flag set by the VBL task indicating that the VBL task 
saved the old cursor and changed the cursor to a watch; so 
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GetNextEvent restores the old cursor. No good! We've 
restored to a watch when we don't want a watch. To avoid 
this, the GetNextEvent hook looks at the cursor saved by the 
VBL task; if it's a watch, it doesn't restore it. 

Also, there are times when GetNextEvent is not called, 
but nonetheless it would be inappropriate to change the cursor 
to a watch: when the mouse is being tracked by, e.g., the 
Menu Manager or the Control Manager. If the user dawdles 
while he has a menu pulled down, we can't change the cursor 
just because GetNextEvent is not being called. So, the VBL 
task will not change the cursor if the mouse button is down. 

The time period used to initialize the VBL counter is 
application-dependent. About half a second works pretty well 
with an application I recently implemented. If the period is 
too short, the cursor will too-often toggle to a watch and back 
in a distracting way. If the period is too long, then the user 
will not be promptly informed that the application is busy, 
and the change of the cursor to a watch will seem unrelated to 
the preceding user action which initiated the time-consuming 
process. 

My implementation of AutoWatch in MDS Assembler is 
shown in Figure 1. This implementation will not work 
under Switcher. 

Move Low 

The 128K ROM has a new feature with regard to the 

loading of CODE segments. If a CODE resource does not 

have the resLocked attribute, then the Segment Loader will 
load that segment as high as possible in the heap. The idea is 
that up at or near the top of the heap, it will be "out of the 
way" and not contribute to heap fragmentation. 

However, this can be a problem with CODE 1, the code 
segment which is loaded first and which is usually the main 
segment of the application. Upon loading, the Segment 
Loader will lock it, regardless of the resLocked attribute, as it 
does for all segments. It will remain locked until the 
applicaton unloads it — but most applications don't unload 
CODE 1. If CODE 1 does not have the resLocked attribute 
(which it will not if generated by, e.g., the Consulair Linker), 
it will be loaded high in the heap - the initial heap before any 
heap expansion has occurred. Since almost all applications 
expand the heap either explicitly or implicitly, the new 
Segment Loader feature is effectively a "load in middle" for 
CODE 1. 

To get around this, I implemented a routine (Figure 2) 
which moves the calling segment to or near the bottom of the 
heap. It consists of two parts: the invoking code, and a 
subroutine which does the actual move. The invoking code 
puts the subroutine on the stack and calls it; the subroutine 
reallocates the calling segment's heap block low in the heap, 
displaces its return address by the distance the segment was 
moved, and returns to the caller, which cleans up the stack. I 
put this code right after a call to MaxApplZone at the 
beginning of my CODE 1 segment. 

The reason the subroutine is executed from the stack is 
that the Memory Manager call which it uses to get space low 
in the heap, _ReservMem, may move the original segment 
which at that point is unlocked. If it does move, and 
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_ReservMem were called from within the moved segment, 
then _ReservMem would return to the wrong place. 

You may notice that after ReservMem, the original heap 
block containing the segment has been released — it's now a 
free block. Nonetheless we copy the segment contents from it 
to the new location low in the heap. That's OK - nothing can 
happen to clobber the freed block between the _ReservMem 
and the. BlockMove. 


; Figure 1 Autowatch routine 
; by Steve Brecher, MacTutor 1986 


XDEF AutoWatch, ShowWatch 
Thanks to Larry Rosenstein for the idea. 


This code must be in a locked segment (e.g., CODE 1). 


Procedure AutoWatch(TickValue: integer); 


If TickValue O 8, install VBL task that will change cursor 
to watch after TickValue ticks since GetNextEvent 
was called, provided that mouse button is not down. 
Old cursor is saved before cursor is changed to watch. 
Installs GetNextEvent hook that restores saved cursor 
and reinits VBL countdown. 
Calls _InitCursor. 
Call AutoWatch with TickValue<>@ just before entering 

your event loop. 

If TickValue = Ø, remove VBL task and GetNextEvent hook. 

Call before quitting application. 


Procedure ShowWatch; 
Unconditionally change cursor to watch. (Must 
have called AutoWatch with TickValue € Ø at 
some time previous.) Typically called right before 
exiting epplication, to cover time until Finder Cor 
whatever is next) comes up. 


"o ew Bw 2o Ww e He We We We Be We We We We Ve we We We We We We We We Ve We We 


Include MacTraps.D 
Include SysEqu .D 
Include QuickEqu.D 
Include Macros see MacTutor Jen. 1986 ie, 
; StackFrame, Arg, Result, Local, Return 
; Pop ..., Push ..., Assume 
; Global variables 
GNEptr DS.L 1 
GNEhookP tr DS.L 1 
GNEreturn DS.L 1 
VBLTicks DS 1 
watchHnd] DS.L 1 
VBLCountPtr DS.L 1 
SavedCursor DS.B cursRec 
isWatch DS.B 1 
; The VBL queue element. 
J 
VBLQE lem: 
DC.L Ü ;link 
DC vType 
DC.L ^ ;task ptr 
DC ø countdown value 
DC ð phase 


: The VBL task code. 


J 

VBL task: 
Move.L  CurrentA5,A2 ;epplication's A5 into A2 
Tst.B — MBState mouse button down? 
Bpl.S el yes, don't change cursor 
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Bset "0, isWatchCA2) ;already make it a watch? 
Bne.S  e1 jyes 
Lea TheCrsr,A0 jno, save current cursor... 
Lea savedCursor(A2), Ai 
Assume CursRec&3 = Ø 
MoveQ — *CCursRec/42-1,D0 

@ð Move.L  (A00*,CAD* 


Dbra DG, 60 

Move.L watchHnd1(A2),A® ;change to watch... 
Push.L (AØ) 

-SetCursor 


61 Lea VBLQElem*vblCount, AQ ;re-init VBL count 
Move VBLticksCA2), CAG) 
Rts 


; The GetNextEvent hock code. It's moved to system heap, 
; which is why we must use a global to store the VBL queue 
; element count field address -- the Lea instruction can't be 


; Used in code that's moved relative to the target of the Lea. 


J 

GNEhook : 
Pop.L GNEreturnCA5) 
Bclr 80, isWatchCA5) jdid we make it a watch? 
Beq.S 61 


jno 
Move.L watchHndl(A5),AØ ;yes, but did VBL task 
j change" watch to watch? (maybe 
, Somebody made it a watch behind our back) 
Move.L (AØ), AØ 
Lea SavedCursor(A5),A1 
MoveQ #(CursRec/4)-1,00 
e  CmpM.L  C(A00*,CAD* ,compare cursor saved by 
; VBL task to watch... 


Dbne DO, 60 
Beq.S 61 ,don't restore if cursor is a watch 
Pea SavedCursor(A5)  ;ok, restore non-watch 
-SetCursor 

81 Move.L GNEptr(A5), AQ ,addr of original GetNextEvent 
Jsr CAB) 390 do GetNextEvent 


Move.L VBLCountPtr(A5),A® ;re-init VBL countdown... 
Move VBLticksCA5)2, CAS) 
Move.L GNEreturn(A5), Ad 


Jmp CAB) ,return to trap dispatcher 
GNEhookLen Equ *-GNEhook 

StackFrame NotLinked 

Arg TickValue, word 
AutoWatch: 

Move TickValueCSP), VBLTicks(A5) ; install or remove? 

Beq.S Remove ;remove 

-InitCursor 

SF IsWetch(A5) 


Lea VBLQElem+vb1Count,A@ ;store addr of VBL 
Move.L  A8,VBLCountPtr(A5) ; queue elem count field 
Move VBLticksCA5), CAS) ; for use by GetNextEvent 
; hook. Init VBL countdown 
; value in queue element. 
MoveQ  #CursRec,DØ ; length of a cursor 
~ResrvMem jmake space low in heap 
Push.L ;room for _GetResource result 
Move.L  *'CURS',-CSP) 
Push 8watchCursor 


-GetResource 

Pop.L A0 

Move.L A@,watchHnd1(A5) ;save handle to watch 
-HNoPurge ,don't let it go away 


Lea VBLQE lem, AQ 

Lea VBL task, A1 

Move.L At, VBLaddr (A0) 

-VInstall ; install the VBL task 
MoveQ GNEhookLen,D1 ;length of our hook code 
Move.L D1,DØ 

-NewPtr,SYS ,move hook code to system heap... 
Move.L AQ,Al 

Move.L  A1,GNEhookPtr(A5) ,Save addr in system heap 
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; for remove 
Lea GNEhook , AQ 
Move.L  D1,00 


-BlockMove 
Move "$170,020 ;GetNextEvent trap! 
-GetTrapAddress 
Move.L — A2,GNEptr (A5) save addr of original code 
Move.L A1,A9 ,addr of our hook code 
Bra.S . SetGNE ,revector GetNextEvent to our 
; hook 
Remove: 


Lea VBLQE lem, Ad 
-VRemove ;remove the VBL queue element 
Move.L GNEhookPtr(A5), AØ 


-DisposPtr ,dispose of hook code in sys heap 
Move.L  GNEptr(A52,A0 ,addr of original GetNextEvent 
SetGNE : Move "$170,008 
-SetTrapAddress ,Set GetNextEvent routine address 
Return 
ShowWatch: 
Move.L watchHnd1(A5), AG 
Push.L (A0) 
-SetCursor 
Rts 
End 


Figure 2 


SegStart: first location in segment (past segment 
header ) 


;Cany data or miscellaneous stuff) 


; MoveLo subroutine. This subroutine is moved to the stack 
and executed from there. 


» Unlock the calling segment, reallocate it low in the heap, 
copy its contents, 

; lock the calling segment, and return to the calling 
segment. 


On entry, AØ = handle to calling segment. 


MoveLo: Pop.L D2  ;return address 
Sub.L (A0),D2  ;D2.W = relative return address 
Push.B . (A0) ;Save Memory Mgr flags in master ptr 
Cir .B (A0) ;make sure not purgeable, unlocked 
-~GetHandleSize ,get his size 
Move.L D0,D1 ,Save size 


-ResrvMem ;make space low in the heap 
» (may move caller) 


Push.L CAB) ,save addr of calling segment 
Move.L D1,D0 ,Size 
-ReallocHaendle ,reallocate handle in low space 


Move.L — A9,D0 ,Save handle 
Move.L — (A40),A1  ;dest addr 


Pop.L A0 ;source addr for move 
Exg D1,D8 ;put size in DØ, saved handle in D1 
-BlockMove ¿copy contents of segment 
Move.L Di, Ad ;hendle 
Pop.B (A0) restore flags in master pointer 
Jmp (41,02)  ;return 
MoveloSize Equ *-MoveLo 
XDEF Start ,4pplication entry point 
Start: Bsr MaxApp1 Zone 


,See "Ask Prof. Mac" Aug. 1985 
; Move this CODE resource down in heap 


a 
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MoveQ t:MoveLoSize,DO ;size of MoveLo routine 


Sub DO, SP make room on stack for routine 
Lea MoveLo, AQ ;source addr 

Move.L SP,A1 ,dest addr 

-BlockMove ;move MoveLo routine to stack 
Lea SegStert-4,AQ ;addr of segment header 
-RecoverHandle ,pess segment handle to MoveLo 

Jsr (A1) ;,call MoveLo on stack 

Add $MoveLoSize,SP ;pop routine from stack 


é 
; The usual initiation rites: 
;€call -MoreMasters here as many times as needed) 
MoveQ *g DO 
SubQ #1,D9 ,all-events mask 
-FlushEvents 
Pea -4(A5) 
-InitGraf 
-InitFonts 
-InitWindows 
-TEInit 
Push0.L 
-InitDialogs 
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Assembly Language Lab 


Panic Button DA Shows Screen Blanking 


Ed Lodwig 
Garfield, NJ 


Asm Link 


Panic Button DA 


It is very difficult these days to find a computing 
magazine that isn't 98% fluff (and meaningless advertisments) 
and 2% useful information. MacTutor is the only magazine 
that I actually look forward to reading each month from cover 
to cover! 

Here is a little gem, just to show my appreciation for all 
the hard work the MacTutor staff puts in each month, and one 
I hope proves useful to our readers as well. Here is a desk 
accessory (very tiny!) taht I wrote using the MDS Assembler. 
Its function is very simple; it's a Panic Button! There are 
probably others that are more sophisticated than this one, but 
sometimes less is more. 


€ File Edit View Special 


A D O m a") 


vee ee ee a d 


Fig. 1 The Panic Button Exposed! 


When you invoke it, you are given a tiny dialog box 
which you can move and hide in a corner of the screen. When 
you are in the middle of your favorite program (doodling in 
MacPaint for example...) and your boss comes along, what do 
you do? HIT THE PANIC BOTTON! When you hit the 
button, the whole screen goes dark as if the Mac is turned off 
and you are save! After the boss goes away, click the mouse, 
and everything is just as you left it. 

There are only two things to remember: First, move the 
mouse away from the spot where you pressed the panic button 
when you click to restore the screen, because if you click 
inside the button again, the whole screen will flash dark again. 
Second, the program grabs about 22K of Storage to save away 
the screen buffer while the screen is dark (and then restores it 
again) so it may not work with large programs that don't leave 
22K of memory in the Mac to spare; however, a simple Alert 
box will be triggered with the message "Not Enough Memory’ 
to inform you of that fact if a memory problem develops. 
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Program Details 


Desk accessories were covered in detail last month in 
both C and assembly, but this little DA is very nicely done 
and easy to follow. In fact, it will serve as a better 
introduction than the more complicated DA published last 
month if you are new to DA programming. As with all DA's, 
we begin with a table of word length constants that tell the 
desk manager where the five entry points of the DA are. These 
five entry points are standard for any type driver application, 
which is what a desk accessory is. The entry points are for 
opening the DA, Closing the DA and control of the DA. The 
other two entry points are normally associated with device 
drivers that require a status check or a prime routine for set-up. 
Immediately after this table of entry points is the string title 
of our desk accessory. 

The three routines for open, close and control then 
follow. In general, the desk manager will pass control to either 
one of these three routines from the currently running 
application depending on circumstances. When the user first 
selects the DA from the Apple menu, the open entry will be 
invoked. When a control in the DA's window is pressed, the 
control entry will be invoked. When the user no longer 
requires the DA and presses the close box, then the close entry 
will be invoked. We must be prepared for the DA to begin 
execution at any one of these three entry points. 


Open and Close 


When we open or close the DA, we first save the 
application's graph port. For some reason, the desk manager 
does not do this for us. Care must be taken to save all the 
registers and especially to protect the contents of AO and Al, 
which contain information vital to the DA. It is very easy to 
forget and make a trap call and find out the DCE pointer is 
messed up because the A1 register was not protected from 
alteration. When the DA is called, register AO contains a 
plinter to the IO Parameter Block and A1 contains the pointer 
to the Device Control Entry Record. These two Structures 
contain all the information the DA needs to find out what to 
do. In the IO Parameter block is a field called csCode which 
we use to branch on to handle the various events passed to the 
DA. This event processing is doine in the Control entry of our 
DA. In the Open and Close entry portions, we make use of the 
Device Control Entry Record to set up any global storage 
space required by the DA. The field dCtlStorage is used to hold 
a handle to any global variable space required by the DA. Both 
the DCE and the IO Parameter block were shown in detail in 
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last months's issue of MacTutor, and are documented in Inside 
Macintosh. 


Resource ID 


One thing we need to do when we open the DA is to 
establish the base ID for our resources. In the top of our DA 
source code, we tell the linker that the code that follows is a 
resource of type DRVR and we give it a resource Id number as 
shown: 


RESOURCE 'DRVR' 25 ‘Panic Button’ 


In fact, this entire source file is all resources! After the 
code resource, we have our ‘traditional’ resources. Anyway, the 
number 25 indicates the Id number for this DRVR resource, 
and hence for our DA. All other resources must be a function 
of this number, because the Font/DA Mover will change the 
DA number when it inserts this DA into the system file so 
that no two DA's have the same Id. The formula for 
calculating the RMaker resource ID number from this DA 
reference number is as follows: 


RMaker ID = (DArefNum X 32) + Index - 16384 


The index is used for owned resources such as Alert 
items, where the resource "owns" other resources. Otherwise, 
it is normally zero. Since our DA reference number is 25, we 
calculate: 


RMaker ID = 25 X 32 +0 -16384 = -15584 


Hence this is the number we would use for our resource 
ID's if we were using the RMaker file to compile our 
resources. It turns out that RMaker has a problem opening a 
"REL" file created by the Consulair C compiler for a DRVR 
Proc type resource. As a result of this bug, I was unable to 
use RMaker to complete the DA so I have translated all the 
RMaker resources into assembly language and have used the 
Consulair linker to create the DA. If your using the MDS 
assembler, simply assemble and link this file with the MDS 
linker. I have to use the Consulair compiler for my MDS 
assembler because I have a Mac Plus and Apple hasen't 
finished fixing the MDS system to run properly under HFS. 
Actually, the Consulair Compiler makes a great MDS 
alternative. But when the 16 bit value -15584 is used for the 
resource ID, the assembler converts this to a 32 bit value of 
FFFF C320 which does not work for a resource ID. So what 
we do is take -15584, convert it to hex with a hex calculator 
(included on the source code disk for this issue) to FFFF 
C320, take the last word, C320 and convert that back to 
decimal, which gives us 49952. This is the decimal value we 
use for our resource ID numbers when coding resources in 
assembly language. 

The last thing we do in our open routine is to set up a 
dialog type window and to save the window pointer back in 
our DCE record and mark that window as a system window 
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belonging to a DA by updating the windowkind field in our 
newly created window record. We then restore the users graph 
port and exit, clearing DO to show the DA executed properly. 

For the close routine, we do much the same thing only in 
reverse. This time we dispose of our window and release any 
global storage we might have referenced to dctlstorage field of 
our DCE record. In this DA, we don't use any storage except 
briefly during our control loop when we blank the screen. 

The Control Loop 


That brings us to the control loop, where the events 
processed by this DA are handled. The IO Parameter block 
entry cscode tells us which event was passed to us from the 
desk manager. In our case, the only event we will see is a 
dialog event when the user presses the panic button. The 
csparam field of the IO Parameter block contains the pointer to 
our event record, so we use that along with our window 
pointer to call _dialogselect, which returns the itemhit with 
the control item that caused the event. If we didn't get an 
event, then we take the control exit through JIODone and 
return to the current application. 

If we did get an event, then that means the user pressed 
the panic button and our job is to clear the screen. Now the 
control entry code does it's work. We first get a handle to 22K 
of storage space so we can copy the current screen contents 
into a safe area on the heap. If this request becomes a problem 
for the Mac, then we check the error code returned in DO to see 
if it's a memory full error, -108. If so, then we forget the 
screen blanking and exit because there is not enough memory 
available to lock up the necessary storage to blank the screen. 
However if it's some other type of error, the routine is 
executed with the assumption that the new handle was 
returned. This might cause a problem but I can't think under 
what circumstances it might happen. If the error is a memory 
full, we display an alert message using our alert resource, and 
then dispose our window and exit through JIODone. Since our 
simple DA doesn't need any attention, we return no error code 
and it's just as if we were never called. 

Assuming no error was returned, we can then blank the 
screen. We do this by locking our handle after saving it in the 
dctlstorage field of the DCE record and then calling our blank 
screen subroutine. When we return, we unlock our handle and 
get rid of the storage space and exit. 


Screen Save 


That leaves only the screen save and get id base 
subroutines to discuss. The screen save subroutine moves each 
byte of the screen buffer to our 22K storage space on the heap 
so it can be restored later, and fills the screen with $FFFF for 
black. A pointer to the base of the screen buffer area is 
contained in the system global location $824. We load the 
screen buffer pointer into A3 and the deferenced handle of our 
screen storage area into A2 and do an indirect move to move 
each word from the screen to the storage. Our loop counter is 
10,943 words of memory or 21,886 bytes of memory. (Note 
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that in the old 128K Macs, after the screen buffer, you have 
just over 100K, and with another 20K for various system 
things like heaps and stacks and such, the poor machine had 
only 80K or so for programs. Since most Mac programs take 
at least 60K, it's no wonder the skinny mac died of memory 
Starvation.) 

After setting the screen black, we loop on the buttonstate 
until it changes and we can then restore the screen and exit. 
The button state is stored in a system global at $172 and will 
be set when a button down event is registered by the system. 

Our resources provide us with a dialog window 
containing a single control item, a button. The DLOG and 
first DITL resources specify our window and panic button. The 
next resource is an alert a sorry button control and a string 
telling the user there is not enough memory. This alert is 
invoked when we detect a memory full error when we try to 
get a handle to 22K of heap space for saving the screen buffer. 
Note that the alert resource "owns it's DITL list and so the 
resource ID of it's DITL list is incremented accordin gly. 

That completes our simple, but fun little DA. Enjoy. 


Assembly Language Source Code 


;Panic Button DA 
; By Ed Ludwig for MacTutor 


RESOURCE 'DRVR' 25 ‘Panic Button’ 


; includes (probably not all are neccesary) 


Include MacTraps.d ; Sys and toolbox traps 
Include ToolEqu.d ; Use toolbox equates 
Include QuickEqu.d ; Use quickdraw equates 
Include SysEqu.d ; Use system equates 
include FSEqu.d ;file system equates 


,ny equates 


$824 
$172 


screenbase equ 
buttonstate equ 


jpointer 
;byte 


; first comes the device control entry table 


&ccentry: 
dc.w $0400 ,;control events only 
dc.w g ,Set only if acc. needs time 
dc.w $0 142 ,event mask 
dc.w Ü jmenu id (none at the moment) 


,0ffsets into routines used by desk manager 


dc.w accopen-accentry ,open routine 
dc.w accdone-accentry ;prime Cunused) 
dc.w accct]-accentry ,contro] routine 
dc.w accdone-accentry ,Status (unused) 
dc.w accclose-accentry ;close routine 

acctitle: ,name of accessory 
dc.b 62-61 

@1 dc.b ‘panic button - by Ed Ludwig’ 

e2 

align 2 

aa a c man Dc 90 1- aaa E 


,Save application port and allocate window 
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&ccopen: 
movem.1 — a7-a4/d0-d4, -Csp) 
move.] 81,84 
Subq.1 84 sp 
move.] Sp,-(Csp) 
-getport 
tst.] dct lwindow(a4) 


,Save registers 
;move dce to safe place 


;make room for the port 
,Push a pointer to it 
,get it, now on stack 


,already have a window? 


bne standardreturn ;ges, non-zero so exit 


bsr getidbase 


jno, make new window 
,get the base id number 


,Space for window ptr 
,Push basenum 

;nil for dstorage 
,get -1 into d0 
,Push behind = -1 
,display 
,pop dialog pointer 


,Save window pointer in dce 


;mark as system window 


,graph port on stack 
;make window current port 
,restore registers 


,Feturn no error 


,Save registers 
,move dce to safe place 


;make room for the port 
,Push a pointer to it 
,get it, now its on the 


,do we have a window? 
nO, go past disposal 
,UeS, prepare to trash it 
,dispose window 
;clear entry in dce 
,goodby window 
»note port still on stack 
;make window current port 
,restore registers 
,return no error 


,Save registers 
;move dce to safe place 
;clear d 


;get control code 
jis it an event? 


,yes, do event 

;clear result 
,Push ptr to event record 
,Push address of itemhit 


;clear boolean 
,ues handle it 


,restore registers 
,return no error 


clr.1 -(sp) 
move.w dð, -Csp) 
clr.1 -(sp) 
moveq 8-1 dg 
move. ] d2,-Csp) 
-getnewdialog 
move. | (sp)+, ad 
move. 1 a0, dct lwindow(a4) 
move .w det lrefnum(a4), windowkind(ag) 
standardreturn: 
-Setport 
movem.] (sp2*,a0-a4/d0-d4 
moveq "g,d0 
rts 
accclose: 
movem.| a0-a4/d0-d4,-(sp) 
move. | 81,84 
Subq.1 84 sp 
move.1] Sp, -Csp) 
-getport 
Stack 
tst.1 dct lwindow(a4) 
beq 81 
move. | dctlwindowCa4), -Csp) 
clr.1 dct lwindow(a4) 
-disposdialog 
81 
-setport 
movem.|  (sp)+,a0-a4/d0-d4 
moveq #0, dø 
rts 
accct!: 
movem.| a@-a4/d0-d4,-(sp) 
move. ] al,a4 
moveq 80 dø 
move .w cscode(Ca£), dø 
cmp i .w Faccevent, dd 
bne done ;no, all done 
clr.w -(sp) 
move.] csparamCa£), -Csp) 
pea dctlwindow(a4) ;push address of dialog ptr 
pea itemhit 
-dialogselect 
move.w (sp2*,d0 
bne whichevent 
done: 
movem.]  (sp)+,a0-a4/d0-d4 
moveq "9 dd 
move.] jiodone, -Csp) 


;jJump to iodone 
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rts DA ref. number. The formula is: RMaker ID = 


whichevent: ; CDArefNum X 32) + (index of owned resources) - 16384 
move.w itemhit,d0 ; where index of owned resources is Ø on up. If our DA were 
subq.w *%1,d0 ;was an item hit? ; 12 then 12 X 32 + Ø -16384 = -16000 which is the RMaker ID. 
bne done jno, all done ; But the asm converts -16000 to a 32 bit number FFFF C180 

jyes, so go to it! ; which doesn't work. So, convert -16900 to hex and use the 
move. | #21888,d8 ;* of bytes on mac screen ; first word: -16000 = FFFF C188, so convert C188 to Decimal 
-newhandle ;get handle to 22K of ; to get 49536, a 16 bit number, which is the assember 

store! ; ID number for DA 12. 
beq everything okay so branch RESOURCE 'DLOG' 49952 'title' 
cmpi.w 1-108, dd ;ho, mem full error? DC.W 295 ;TOP 
bne 87 ;ho, go on to branch DC.W 399 LEFT 

;Ccould this happen?) DC.W 325 ;BOTTOM 

e6 ;,yes, display error alert DC.W 492 ;RIGHT 
bsr getidbase ;get base id num in dð DC.W 4 ,window type 
clr.w -(sp) ;Save space DC.B 1 visible (T=1/F=0) 
move.» . d0,-Csp) ;push basenum DC.B Ø ignored (part of visible) 
clr.1 -(sp) ;nil for filter proc. DC.B 1 ;goaway box (l=yes, £-none) 

-alert display alert DC.B Ø ;ignored (part of goaway) 
move .w (sp )+, dø ;pop result DC.L 0 ;refcon 

;prepare to exit DC.W 49952 ;id of DITL list 
move. | dct lwindow(a4),-Csp) DC.B 62-81 ;length byte 
clr.1 dctlwindow(a4) ;clear entry in dce e1 DC.B 'Don',39,'t'  ;window title 
-disposdialog ;dump window @2 
bra done exit „align 2 

67 ;got handle ok RESOURCE 'DITL' 49952 'Button' 
move.1 aü,dctlstorage(a4) ;save handle in dce DC.W Ø ;number of items -1 
move. | að, a2 Set up screen save DC.L @ ;hendle holder 
-hlock ;lock handle DC.W 5 , top 
bsr screensave ;do the save and restore DC.W 16 ;left 
move. | dct lstorage(a4), ad DC.W 25 bottom 
-hunlock unlock storage DC.W 77 right 
move. | dct Istorage(a4), ab DC.B 4+8 ;item type Ccntrl button) 

-disposhendle ;dispose storage (22k!) DC.B 64-83 ;item length Ceven) 
clr.1 dctlstorage(a4) ;clear storage e3  DC.B 'Panic!' sitem itself — 
bra done exit 84 
pumeemuemmesecue qe SUBROUTINES” ;meseSERESERS ERE Roe uu „ALIGN 2 
screensave: ;clear and save screen RESOURCE 'ALRT' 49952 'error' 
jenters with handle to storage DC.W 254 ;top 
-hidecursor ;hide for proper restore DC.W 334 ;left 
move. | (a2), a2 ,derefence handle DC.W 320 ;bottom 
move. | #19943,d1 ;set loop index DC.W 491 ;right 
moveq *0,d0 ;set screen index DC.W $C321 ;resource ID of DITL list (49953) 
move. 1 screenbase, 83 ;base address of screen DC.W $4444 ;stages 

e1 ;move word from screen to storage ALIGN 2 
move.w . £(e3,d0.12,0Ca2,d0. 1) RESOURCE 'DITL' 49953 'msg' 
move.w . "$ffff,0Ca3,d0.1)  ;black out screen word DC.W 1 ;number of items -1 
aeddq.] %2,d0 ;inc screen index DC.L Ø ‘handle holder 
dbf d1,@1 ,dec loop index DC.W 33  ;top 
moveq  "Ø,dð DC.W 8; left 

62 DC.W 55 bottom 
move.b — buttonstate,d0 ;user press button? DC.W 137 ;right 
bne 82 jno, wait until it is DC.B 4*0 ;item type Ccntr] button) 

,yes, restore screen DC.B e6-65 ;item length Ceven) 
move.] . *10943,d1 ;set loop index 65  DC.B 'Sorry!' ;item itself 
moveq #9, dø ,set screen index 06 . 

e3 ;move word from storage to screen DC.L Ø ;handle holder 
move. | 0(82,d0.12,0C(a3,d0.1) DC.W 3 ;top 
addq. | #2, dø j inc screen index DC.W 5 “left 
dbf di,@3 ;dec loop index DC.W 22  ;bottom 
~showcursor ;restore cursor DC.W 145 ;right 
rts ; , return. DC.B 128+8 jitem type (disabled static text) 

getidbase: exits with base id number in dø DC.B 68-67 ;item length Ceven) 
moveq 80, dø clear dø 67 DC.B ‘Not enough memory. ';item itself 
move.w .— dctlrefnum(a42,d0 ;get reference number e8 
eddq.» — "1,d0 jand calc base number END 
muls ®-1,d0 ;for resource id 
mulu *32,d0 ; Link file for panic da 
add.w "$0000, dd ] 
rts /Resources 
aah ca aa ECC a G08 7 Ses en seas panic 

itemhit dc.w Ø [output panic button 

/Type 'DFIL' 'DMOV' i 
pea pee eee Te Resources ------------- $ 


resource ID numbers must be negative functions of 
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Graphics Lab:Asm 


Chris Yerga 


BitNapper DA Steals Bit Maps! sman Flight Demo 


Anguish and Fear 


Welcome to the first installment of the Graphics Lab. This 
is where we really see what the graphics capability of the 
Macintosh is like. This month's column will discuss desk acces- 
Sories and the techniques necessary to implement them using 
MDS, and in particular, the marvelous BitNapper DA, which will 
become very important to us next month. I have always had 
problems understanding what desk accessories really are and 
why mine never worked. Consequently, when I realized that I 
needed to write a DA to simplify the development of a game, I 
was wracked with apprehension. So my special thanks go to 
BMUG's Dave Burnard, who taught me how to write desk 
accessories without even realizing it. Thanks Dave. 


Cutting Up 


First, lets discuss what the desk accessory will do. The 
BitNapper DA's, function is to allow the user to "cut" rectangular 
reigons from the screen image. The DA will then create a bitMap 
out of the data, format it as an MDS source file, and write it out 
to disk. This allows us to cut graphics from MacPaintor any other 
application that supports desk accessories, and use them in our 
own MDS programs. More details on this technique will be 
presented next month when we use our BitNapper DA with 
another graphics program to create animated effects. 

Since we want access to graphics anywhere on the screen, 
it is undesirable to have our desk accessory based in a window 
which will cover up some area of the screen. Asa result, we will 
make our DA menu based. When the desk accessory is opened, 
it will install it's own menu in the menu bar, and it will remove 
the menu when it's closed. 


The essence of desk accessories 


Now lets take a look at the desk accessory itself. From a 
low-level veiwpoint, a desk accessory is a device driver. That is, 
desk accessories and device drivers are structured sim ilarly. The 
structure that they share is somewhat different from that of a 
standard Macintosh application, and consequently, the pro- 
gramming approach is a bit different. To understand why this is, 
lets look at figure #1. 


Figure #1 shows the structure of a DA header. The first 
word, drvrFlags, specifies what types of calls are supported by 
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Figure #1 
Desk Accessory Header 
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the desk accessory, whether it needs to be called periodically, 
etc. Our DA will set this to indicate that Control calls are 
supported, and that the accessory should be locked in memory 
after it's loaded. The following word is drvrDelay, which 
determines how often, in ticks, the desk accessory needs to be 
called. Since we don't need to update an on-screen clock or 
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perform any similar task, we don't require periodic calls and will 
set this field to NUL. 

The next word, drvvrEMask, is the event mask for our DA. 
We will set ours to NUL, because our DA doesn't respond to 
event manager events. Rather, our DA will respond to desk 
manager events that are sent when a menu item is selected. The 
ID of the menu belonging to our DA is stored in the next field, 
drvrMenu. 

The following 5 words are offsets to the Open, Prime, 
Control, Status, and Close calls relative to the beginning of the 
desk accessory. The Open routine is called when the DA is first 
opened, and is responsible for defining and installing the menu, 
and other initialization tasks. The Prime routine is called when 
the accessory needs a periodic event, our Prime routine simply 
returns. The Control routine is the heart of the DA, and is 
responsible for handling events. Our DA has no Status routine, 
since itis not appropriate. Finally, the Close routine removes the 
DA's menu and frees up any storage allocated by the DA. 

Following the offsets is an optional name for the desk 
accessory. This is not where the name that appears in the menu 
bar is stored; rather, this is available for internal use by the DA. 
For example, a DA could look here to find the tide for it's 
window, etc. We don't use this name. The remaining data is the 
actual code for the DA's routines. 


But wait, there’s more... 

There is another data structure that we must concern our- 
selves with. This is the Device Control Entry. The DCE is a 40 
byte relocatable block that is allocated on the system heap when 
a desk accessory is opened. As illustrated in figure #2, the DCE 
contains various information about the DA, and copies of some 
of the data in the DA header. Although it is primarily intended for 
internal use by the device manager and the desk manager, there 
are a couple of fields relevant to our discussion. 

The DCE contains a field which the DA may use to store a 
handle to some private storage which it allocates. This field, 


dCuStorage, will be where we store the menuHandle for the 
DA's menu. 

Another important field is dCt1}Window, in which the DA 
may store the windowPtr of it's main window. Its purpose is 
analogous to our use of dCtlStorage for DA's which are window 
based. For such DA's it is important to set the windowKind field 
ofthe window record to the DA's driver reference number, which 
is located in dCtIRefNum. This marks the window as belonging 
to a DA, and insures that Desk Manager and Event Manager 
routines work properly. 


The tables are turned... 


We have dealt with register-based calling conventions in the 
past. This is where arguments are passed in a data structure 
pointed to by an address register rather than on the stack. But this 
time we are on the receiving end. Instead of us having to set up 
the proper fields of a parameter block, we are passed parameter 
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Figure #2 
Device Control Entry 
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blocks to use or ignore as we wish. When a DA routine is called 
AO contains a pointer to the IOParamBlock and A1 contains : 
pointer to the DA's DCE. When a DA routine is finished, it mus 
send an error code back in DO. If DO is cleared, then no error has 
occurred. 


For openers 


The first thing the Open routine does is save the registers o 
the stack. Next, it copies the DCE pointer from A1 into a less 
volatile register. Then it makes sure this is the first call to the 
Open routine by testing the dCtlStorage field of the DCE. If there 
isn't a menuHandle stored here (it's NIL) then a menu is created 
and the menuHandle is stored, otherwise it just returns. 

The Close routine does the opposite. It removes the men 
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from the menu bar, releases the memory occupied by it, and 
clears the dCtlStorage field. 

The Prime and Status routines don't exist, so the offsets in 
the DA header point to a routine called Null which simply clears 
DO to signify that no error has occurred and returns. 


On with the show 


The Control routine is the functional element of the DA. 
Whenitis called, itchecks the csCode field ofthe IOParamBlock 
to see if an event of interest has occurred. There are 9 possible 
messages passed in csCode; they are listed on page 14 of the 
Desk Manager Programmer's Guide in Inside Macintosh. 
However, our DA only acknowledges 1 of these messages. 

This is accMenu, which has a decimal value of 67. When 
an accMenu message is passed to a DA, the csParam field of the 
IOParamBlock contains the MenuID of the menu and csParam+2 
contains the item number. SInce we only have one menu, we 
don't need to check the MenuID. Rather, we check the item 
number to determine which command was selected. 

One of the menu items is Word Constraint, which is toggled 
on and off by repeated selctions. What this does is force the 
rectangular regions to have widths which occur on word bounda- 
ries; this is a convenient format for certain graphic applications. 
When this item is selected, the DA calls _GetItmMark to 
determine if the item is checked. It toggles the appearance of the 
item with CheckItem and returns. 

The main menu item is Steal Bits. When this is called, the 
cursor is hidden and is replaced by a small rectangle which 
inverts whatever it is currently over. The user positions this at the 
upper left corner of the region he wants to steal. Then the user 
drags to the lower right of the region. The routine inverts the 
rectangular region selected until the mouse button is released. 

When the button is released, the DA calculates the relevant 
information needed to create a BitMap data structure containing 
the selected bits. When this is done, a nonrelocatable block of 
proper size is allocated on the application heap and the screen 
data is copied via. CopyBits. The user is then prompted for a 
filename via SFPutFile and so on. I won't gointo detail about this 
portion of the DA, as it is very similar to my icon converter in 
Vol. 2 No. 1. of MacTutor. That issue also contains additional 
information about the structure of BitMaps, if the above seems 
unclear. 


Get it where it counts 


Before wecan use the DA, we must install it into the S ystem 
file. A DA isaresource of type DRVR. Atthe beginning of the 
source file we use the Resource directive of MDS to assemble the 
code into a DRVR resource. After linking, the DA can be 
installed into System viathe font/DA mover by holding down the 
option key and clicking on the open button. This allows us to 
open the output file which contains our DA resource. Other more 
tedious options include using the resource editor, resource 
mover, etc. During development of a DA, I usually just link the 
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-REL file of the DA into the resource fork of a shell application 
that does nothing else but support DA's. This saves me from the 
tedious work of installing the DA after every assembly. 

I hope that I have shed some light onto desk accessories. If 
you are interested in this particular DA or graphic techniques in 
general, more specific information will be coming next month in 
our special animation issue. Enjoy! 


j BitNapper 
; by Chris Yerga 
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RESOURCE 'DRVR' 27 'BitNapper' 


INCLUDE MacTraps.D 
. TRAP -MakeF ile $4008 
MACRO Center String MidPt,Y = 
LEA '(String)',A3 ;get stringPtr 
MOVE.L * (MidPt), D4 
MOVE "t (Y), D5 
BSR CenterText 
| 
MACRO ErrCheck = 
TST.L DØ ,error code? 
BNE I0Err syes...show a dialog 


; Program constants ---- 


Chicago EQU Ü 

Geneva EQU 3 

accMenu EQU 67 ,event code for a Menu event 
csCode EQU 26 ,cnirl code offset in ParamBlock 


ScreenBits EQU $FFFFFF86 
dCtIStorage EQU $14 
[handle] 

dCtlRefNum EQU $18 
dCtlWindow EQU $ 1E 


; [Bi tMap] 
,driver's private storage 


,refNum of this driver [word] 
driver's window Cif any) 


[pointer] 
JIODone EQU $8FC — ;I0Done entry location [pointer] 
Start: 
DC.W $4400 ;ctl-enable & lock it 
DC .W g ,doesn't need time 
DC.W $0000 ;no events 
MenuID: DC.W - 12548 ; menu 


DC.W Open-Start 
DC.W Null-Start j; prime - unused 
DC.W Control-Start ; control 

DC.W Null-Start ; Status - unused 
DC.W Close-Start ; close 


; Open routine 
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. ALIGN 2 


Open: Ct1Done: 
MOVEM.L A0-A6/D0-D7,-CSP2;Save the registers MOVEM.L CSP2*,A0-A6/D0-D7;restore the registers 
MOVE.L A1,A4 ;get a copy of the DCE in M MOVE 89 Dd ; return no error 
MOVE.L — JIODone,-C(SP) ; jump to I0Done 
;Check if we already have a menu. RTS 
;If one exists, its handle would be stored in dCtlStorage 
;Otherwise, dCtlStorage would be NIL DoCtlEvent: 
CMP $1, 30CA0) ;is it Steal Bits? 
TST.L DCtlStorage(A4) BEQ GetBits 
BNE Restore ;we have one...skip this code CMP 85, 30CA0) sis it quit? 
BEQ ItsQuit 
;0K. We need to create our menu: CMP $2 ,30CA0) sis it constrain? 
BEQ Constrain 
CLR.L -(SP) ;room for menu hendle CMP "3, 30CA0) ;is it About? 
LEA MenuID, Ad BEQ About 
MOVE (A0),-CSP) jmenu ID BRA Ct1Done 
PEA 'BitNepper' ;henu title 
-NewMenu About: 
MOVE.L CSP), dCtIStorage(A4) ;save handle, on stack CLR.L -(SP) ;room for WindowPtr 
PEA ‘Steal Bits; Word Constraint; About BitNapper;- CLR.L -(SP) ;allocate storage in heap 
jQuit’ PEA. WindowRect j bounds 
-AppendMenu PEA ‘Title?’ title. .unused 
MOVE.L  dCtiStorage(A4),-CSP);push handle MOVE "$0101,-(SP)  ;visible 
CLR -(SP) ;put at the end of menu bar MOVE #1,-(SP) ;dialog-style window 
-Inser tMenu MOVE.L 8-1,-(SP) sput it in front 
MOVE .L dCtlStorageCA4)2, -CSP) ; menu handle CLR -CSP) ;noGoÀway 
MOVE 84,-C(SP) sitem 83 CLR.L -CSP) ;refcon 
-DisableItem ;diseble it -NewWindow 
-DrewMenuBar ;drew the new menuBar MOVE .L CSP)+,A2 ;save windowPtr 
PEA thePor t ;VAR thePort 
Restore: Ge tPort ;seve current grafport 
MOVEM.L CSP2*,A0-A6/D0-D7; restore regs MOVE.L — A2,-CSP) ;make help window current port 
Null: -SetPort 
MOVE 20,00 ,return noErr MOVE "Chicago,-(SP) ;set font 
RTS jand return... _TextFont 
MOVE 812,-CSP) ;12 point 
Close: _TextSize 
MOVEM.L A0-A6/D0-DT , -CSP);save registers Center the BitNapper, 178,20 
MOVE.L A1, M ;copy DCE to A4 MOVE Geneva, - (SP) 
_TextFont 
LEA MenuID, A2 ;Get the Menu ID MOVE "9. -(SP) 
MOVE CAB), -CSP) ;remove menu from list _TextSize 
Dele teMenu ;MenuHandle stored in dCtlStorage Center ©1986 by Chris Yerga, 178,30 
MOVE.L — DCtiStoregeCA4), -CSP) MOVE #12,-(SP) 
-DisposMenu ;free up its memory _TextSize 
-DrewMenuBar ;draw the menubar Center The BitNapper is a tool which simplifies, 178,50 
CLR.L DCtlStorageCA4) ;remove MenuHandle Center the use of BitMapped graphics with the MDS 
system., 178,62 
MOVEM.L (SP)+,AQ-A6/DO-D7; restore regs Center — It allows the user to cut bitmaps directly 
MOVE #9 Dd ;return noErr off , 178,74 
RTS ,and return... Center the screen from any application that sup- 
ports, 178,86 
Control: Center desk accessories., 178,98 
MOVEM.L AØ-A6/DØ-D7,-(SP); save registers Center To learn about graphic techniques and all 
MOVE.L A1,A4 ;copy DCE pointer to A4 other, 178, 115 
MOVE csCode(A02,00 ; get the control opCode Center aspects of Mac programming read MacTutor maga- 
CMP ®accMenu, DØ ; is it a menu event? zine., 178, 127 
BEQ DoCtlEvent ; yes, do it... MOVE #1,-(SP) 
54 
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-TextFace 
Center call (714) 630-3730 to Subscribe, 178, 150 
@1 CLR -(SP) 


-Button 
MOVE (SP )+, DØ 
BEQ ei 
MOVE.L thePort,-CSP) srestore the old grafport 
-SetPort 
MOVE.L A2, -CSP) j lose the window and free 
-DisposWindow jup it's memory 
CLR -(SP) ,unHiLight the menu 
-HiliteMenu 
BRA Ct1Done 

CenterText: 
CLR -(SP) ,room for INTEGER 
MOVE.L A3, -CSP) ;push stringPtr 
-Str ingWidth 
CLR.L D3 
MOVE (SP)*,D3 ;get string width 
DIVU #2,D3 
SUB D3,D4 ;Subtract width/2 from center 
MOVE D4, -CSP) ;push x 
MOVE D5, -CSP) ;push y 
-MoveTo 
MOVE.L A3, -CSP) 
-DrewStr ing 
RTS 

Constrain: 


MOVE.L — dCtlStorage(A4), -CSP) ;menuHandle 
MOVE "2, -(SP) jitem #2 


PEA CheckMark ,VAR CheckMark 

-GetItmMark 

CLR DØ ,Set marked to FALSE 

LEA CheckMark , A1 

TST (A1) jis it marked? 

BNE e1 ,Yes..lets unmark it 

MOVE 1*$0 101,00 ,Set marked to TRUE 
@1 MOVE.L dCtlStoregeCA4), -CSP) ; menuHandle 


MOVE $2, -(SP) 
MOVE DØ, -CSP) 


jitem #2 
;marked: BOOLEAN 


-CheckItem 
CLR -(SP) ,unHiLight the menu 
-HiliteMenu 
BRA Ct1Done 
Sync: 
SUBQ 84,SP ;Room for result 
-TickCount 
@1 SUBQ 84,SP ;Get it again 
-TickCount 
MOVE.L (SP)*,D0 ;Get tickCount in DØ 
CMP.L (SP), DØ jHas it changed? 
BEQ ei ,No, loop 
ADDQ #4,SP ;else pop old tickCount 
RTS jand return 
GetBits: 
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eg 
e1 


82 


e3 


84 


PEA thePort 
-GetPort 
MOVE.L dCtlStorageCA4), -CSP) ;menuHandle 


,Sa8ve the GrafPort 


MOVE 82 -(SP) jitem #2 

PEA CheckMark VAR CheckMerk 
-GetItmMark ,Ssee if it's marked 
MOVE "$FFFF ,D4 ;8Ssume no constraint 
LEA CheckMark ,A 1 

TST (A1) jis it marked? 

BEQ eo ,ho...no constraint 
MOVE “$FFFO,D4 jyes...word constraint 
-HideCursor ;hide the cursor 
PEA StartPoint ;VAR MousePoint 

Ge tMouse ,get the mouse location 
PEA StartPoint 

-LocalToGlobal ,convert to global coordinates 
LEA StartPoint,A3 

AND D4,2CA3) ;constrain the horiz coord 

MOVE .L (A3), 4CA3) ;lopLeft of rect 

ADD 84, 4CA3) ;add 4 to bottom 

ADD 816,6CA3) jadd 16 to right 

MOVE.L A3,-CSP) 

-InverRect ;invert the rect 

BSR Sync ;wait for a couple VBL's 
BSR Sync 

MOVE.L A3,-CSP) ; invert it again 

-InverRect 

CLR -(SP) ,BOOLEAN 

-Button ,See if Button is pressed 
MOVE (SP)+,D8 ;get result 

BNE 62 ;button was pressed 

BRA e1 snot pressed...continue 
PEA StertPoint ,drew the rect 

-InverRect 

PEA NewPoint ;VAR NewPoint 

-GetMouse ,get the mouse location 

PEA NewPoint 

-LocalToGlobal ,convert to global coordinates 
LEA NewPo int, A3 ,get ptr to NewPoint 

AND D4,2CA3) ;constrain the horiz 

MOVE.L (A32, DØ ,get newpoint 

LEA EndPoint, A3 

CMP.L (A32, DØ ,has it changed? 

BEQ 84 ;ho...check for Button up 
BSR Sync 

PEA StartPoint ,yes...erase old rect 
-InverRect 

MOVE.L 4CA3), (A3) jmake Point the new EndPoint 
PEA StartPoint 

-InverRect jand invert the new rect 

CLR -(SP) 

-Button ;Button up? 

MOVE (SP +, DØ 

BNE 63 ;NO... keep going 

PEA StartPoint 

-InverRect ,erase the rect 

CLR -CSP) ;room for BOOLEAN 
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PEA 


Emp tyRect 


Star tPoint 
;is the rectangle empty? 


MOVE (SP)+,D8 ;get result 

BNE StealExit ,Yes...get lost 

LEA StartPoint,Al ;get pointer 

LEA NewPoint, Ad get pointer 

MOVE .L (A12,CA0) ;copy TopLeft 

MOVE.L 4(A12,4CA0) ;copy BottomRight 

MOVE.L CAG), -(SP) ;SrcPoint 

PEA 4(A0) SVAR DestPoint 

_SubP t ;Subtract SrcPt from DestPt 
jand store result in DestPt 

LEA NewPoint, AG ;get pointer 

CLR.L (A0) ;set topleft = 0,0 

MOVE 6(AB), DB ;get Right in DØ 

ADD “$F DO 

LSR "3,D0 ;divide by 8 to get rowBytes 

AND "$FFFE,DO 

MULU 4(A02,D0 ;multiply by the height 

ADD #26 , 08 make room for header 

LEA BitMapLen, A 

MOVE.L DØ, CAB) ;save the length 

_NewP tr ;get a nonrelocatable block 

ErrCheck 

LEA BitMapPtr, Al 

MOVE .L AB, CA1) ;save pointer 

MOVE.L AO, A4 ;copy to A6 

LEA NewPoint, Ad ;get pointer 

MOVE 6CA0), DØ ;get Right in DØ 

ADD "$F DO 

LSR 83,D0 ;divide by 8 to get rowBytes 

AND #$FFFE, DØ 

CLR. L CA4 )+ ;clear space for BasAddr ptr 

MOVE DØ, CA4)+ ;store rowBytes 

CLR.L CA4)+ topLeft of Bounds 

MOVE.L ACAO), CA4 )+ bottomRight... 

MOVE .L €A1),A1 jget pointer to storage again 

MOVE.L A4, CA1) ;Store basAddr 

MOVE.L CAD), Ad ;get globalPtr 

PEA ScreenBitsCA2) ;srcBits 

MOVE .L A1,-CSP) ;destBits 

PEA Star tPoint ;srcRect 

PEA NewPoint ;destRect 

CLR -(SP) ;hode = srcCopy 

CLR.L -(SP) ;no maskRgn 

-CopyBits ;copy the data from the screen 
;to our BitMap 

PutFile: 
-ShowCursor 


MOVE #100,-(SP) 
MOVE "8g, -(SP) 


;X coordinate of dialog 
;y coordinate 


PEA ‘Save BitMap as: ' ;prompt 
PEA ‘Untitled. BMAP ' ;default name 
CLR.L -(SP) ;standard dialog 


PEA SFReply 
MOVE 81,-CSP) 


;reply record 
;routine selector 
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-Pack3 
LEA SFRep ly, A 
TST.B (AQ) ;were we successful? 
BEQ PurgeB i tMap ;no... 
LEA IOParem, A2 ;ptr to ParamBlock 
CLR.L 12C(A2) ;no completion 
LEA FileName, Ad 
MOVE.L AB, 18CA2) ;filename ptr 
MOVE VRef ,22CA2) Vref Num 
CLR.B 26(A2) vers # 
MOVE .L A2, AS 
-MakeF ile ;create the file 
ErrCheck jare we ok? 
MOVE .B #2,270A2) ;write-only access 
LEA APBuf fer , Ad 
MOVE.L AØ, 28CA2) access path buffer 
MOVE .L A2 , Ad 
_Open ;open the file 
ErrCheck ;ok? 
MOVE.L BitMapLen,D4 ;get length 
LSR.L #3,D4 divide by 8 
MOVE .L BitMəpPtr,A3 ;get ptr to data 

DoALine: 
LEA LineBuffer,A1 
MOVE #7,D3 ;8 bytes per line 
MOVE .L 8'DC.B',CAD* ;store the line header 
MOVE.B 8 ' CAD* 

@1 MOVE.B CA3)+,DØ ;get the next byte of data 
BSR HexToAscii convert it 
MOVE.B — 8'$', CA1)+ ;store it as $xx 
MOVE D1,CA12* 
MOVE.B Bi ICAD* 
DBRA D3,e1 ;have we done 7 bytes? 
SUBA 81,A1 jyes...finish the line 
MOVE .L %$200D2020, CA1)+ 
LEA LineBuffer,A®@ ;and write it to disk 
MOVE .L AD, 32CA2) ;ptr to our line of text 
MOVE.L 838,36(A2) jwrite 38 bytes 
CLR 44(A2) standard positioning 
CLR.L 46CA2) 
MOVE.L A2, Ad 
Write rite it 
ErrCheck 
DBRA D4, DoAL ine jare we done? 

jyes...finish it off 

CLR 28C(A2) 
MOVE.L A2,A0 
-GetFileInfo 
Err Check 
MOVE.L 8'TEXT',32(A2) ;set the filetype 
MOVE .L 8'EDIT',36CA2) jand the creator 
MOVE.L A2,A0 
-SetFileInfo 
ErrCheck 
MOVE.L A2, Ad ;close the file 
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-Close 

ErrCheck 

MOVE.L A2,A0 ;flush out any buffers 
-FlushVo1 

ErrCheck 


PurgeB i tMap: 
LEA BitMapPtr,A@ — ;get ptr 
MOVE.L CAB), A0 
-DisposPtr ,release the block 
StealExit: 
MOVE.L thePort,-(SP) ;restore the grafPort 
-SetPort 


-ShowCursor 
CLR -(SP) ,unHiLight the menu 
-HiliteMenu 
BRA CtlDone 

ItsQuit: 
LEA MenuID, A1 
MOVE (A12, -CSP) ,remove the menu from the list 
-DeleteMenu 
move. 1 DCtlStorage(A4),-CSP);push the handle 
-DisposMenu ;free up the memory 
—DrawMenuBar 
clr.1 DCtlStorageCA4) jno longer have a window. 


MOVEM.L CSP2*,A0-A6/D0-DT7 restore regs 
MOVEQ "9 DO 
RTS 
; HexToAscii routine -> converts a hex byte to an ASCII word 


, On entry: 
k DØ = Hex byte to be converted 


; On return: 
5 D1 = ASCII word result 


, uses D0,D1,D04,A0 


HexToAscii : 
MOVE.B D0,D2 Save copy of byte 
LSR "4,D0 ;Get the high nibble 
ANDI 1*$0F ,DO ,hask out all extraneous bits 
LEA ByteTable,A® ;Get base address of table 
MOVE .B (A0,D0),D1 ,Move Ist ascii byte into D1 
ASL #8,D1 ,move byte to the proper position 
ANDI #$ØF D2 ,get the low nibble 
MOVE .B CAO, D2), DØ jGet 2nd ascii byte 
OR .W D0,D1 ,Store 2nd byte in word 
RTS 

ByteTable: 
DC.B '8123456789ABCDEF ' 

I0Err: 
MOVE DØ, D6 ,get a copy of the error code 
CLR.L -(SP) ,room for WindowPtr 
CLR.L -(SP) ,allocate storage in heap 
PEA ErrorRect ; bounds 
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PEA 

MOVE 
MOVE 
MOVE.L 
CLR 
CLR.L 
-NewWindow 
MOVE.L 
PEA 
-GetPort 
MOVE.L 
-Se tPort 


MOVE 
-TextFont 
MOVE 
-TextS ize 
Center 
Center 
Center 
MOVE.L 
MOVE 
LEA 
MOVE 
EXT.L 
MOVE 
-Pack7 
MOVE.L 
BSR 

61 CLR 
-Button 
MOVE 
BEQ 
MOVE.L 
-SetPort 
MOVE.L 
-DisposWin 
BRA 


CheckMark 
StartPoint 
EndPoint 
NewPoint 
Bi tMapPtr 
Bi tMapLen 
thePort 


WindowRect 
ErrorRect 


] 


; Link file for BitNapper da 


/Resources 

BitNapper 

/Output BitNapper.code 
/Type  'DFIL''DMOV' 
$ 


Title?' ;Vitle..unused 
"$0101,-CSP) visible 

81,-CSP) ,dialog-style window 
8-1,-CSP) ;put it in front 
-CSP) ,noGoAway 

-CSP) ,refcon 


(SP)+,A2 ;save windowPtr 
thePort SVAR thePort 

,Save current grafport 
A2,-CSP) ;make help window current port 


"Chicago,-(SP) ;set font 
812 -CSP) ;12 point 
That operation was interrupted by an, 158,30 


I/0 error. Meke sure that your disk is, 158,43 
not write-protected., 158,56 


8158,D4 ;nidPoint 

#75,D5 ,Y coordinate 

ErrString,A® — ;stringPtr 

D6, DØ ,get the error code in DØ 
DØ ;extend to 32 bit precision 
#9 ,-CSP) ,routine selector for numtostring 
AD, A3 

CenterText ,display the error code 
-CSP) ;wait for a button press 
(SP +, DØ 

81 


thePort,-(SP) ;restore the old grafport 


A2,-CSP) ; lose the window and free 
dow jup it's memory 
PurgeB i tMap ¿clean up and exit 


DC.W ", ,determine if item is checked 
DC.L 9 ,topLeft of rectangle 

DC.L ø ;bottomRight 

DC.L 0,0 ;temp storage of points & rects 


DC.L 9 ,pointer to bitMap mem block 
DC.L "j length of bitMap mem block 
DC.L ø ;temp storage for grafPtr 


DC.W 60, 78, 228, 434 
DC.W — 100,98, 185,414 


—. 
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Resource Roundup 


David Wilson 


Resource Formats for Asm, RMaker and Lisa 


Creating Resources 


When I first began to program the Mac, the accepted way to 
create resources was to define them in a text file (named some- 
thing like ExampleR.text) using the Lisa Workshop. You then 
ran the text file through the Lisa's RMaker to compile this high- 
level "resource language" into the correct format for each re- 
source on disk. 

In the Fall of 1984, I began to present Apple's three-day 
Macintosh Technical Training seminars, designed to teach the 
basics of Mac programming, and we used this approach to do our 
in-class programming with the Lisa Pascal Workshop. 

Things have gotten more complicated during the last year, 
with the development of various utility programs to help you 
create and modify resources, and even decompile them into text 
files. Furthermore, as the readers of MacTutor long ago recog- 
nized, programming directly on the Mac has grown tremen- 
dously in popularity. Many programmers still use the text file 
approach, but use the RMaker that runs on the Mac - one with a 
slightly different format from that used on the Lisa. 

I had to deal with these format differences when we devel- 
oped Apple's new four-day Macintosh Programing Seminars , 
using TML Pascal on the Mac for in-class programming. I had to 
convert my sample programs' source code from the Lisa Work- 
shop to TML Pascal, and finally created the table that follows to 
help in the process. It is presented here in the hope that you will 
also find it useful. 

"But wait", you cry! "I never use a Lisa - why should I care 
about it's obscure RMaker format?" Good question. Here are 
some answers: 


1. Therearestill many Lisa sourcecode samples, from Appleand 
other sources, that you may want to use. This table will help 
you painlessly convert them to your Mac development system. 


2. There are useful utility programs, such as DialogCreator 
and REdit that produce text files only in the Lisa format. 
Again, you must do the conversion. 


3. Other utility programs, such as ScrnEdit, will produce text 
files in either format, but the text files often become a bit 
garbled in the process - you will need some reference to put 
things in order, and the table may also be helpful in that case. 


Of course, you may have decided not to use text files at all, 
since resources can be created directly with ResEdit, and "in- 
cluded" with the RMakeror Linker step. The disadvantage to this 
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approach is that you lose the documentation provided by the text 
files, and you sometimes will have more difficulty in exactly 
aligning the rectangles for scroll bars, dialog items. etc. 


Inany case, good luck in your Macintosh programming, and 
remember Scott Knaster's motto for all Mac programmers: 
"Everything you know is wrong." 


[For those of us fanatics that insist on doing our resources in 
assembly language, we've also included the assembly formats 
from an earlier issue of MacTutor, listed below. Following the 
assembler formats are the RMaker resource formats for both the 
Macintosh and the Lisa. -Ed.] 


Assembly Resource Formats 


Resource Prototypes for Assembler usage 
by 
Frank Alviani 


wee We We We We 


NOTES - 


« Wwe 


b 

; ALL resources using local labels (labels starting with 8) 
; must be bracketed by regular labels; local labels can be 
; re-used only if the duplicates are separated by regular 

; labels. This applies even if no warning appears in the 

; resource prototype! 


These are arranged roughly alphabetically, altho the 
DLOG/ALRT/DITL are grouped together at the end. 


In general 5 represents a numeric field normally filled in. 
The name and attribute fields on the RESOURCE line are 
optional. 


to the resource file being built as needed. This will 
hopefully speed the process, and give flexability the 


d 
4 
; The idea is to have this in one editor window, and to copy 
r 
; RMaker doesn't. 


There are some additional explanatory comments with 
var ious resources. 


Some of this is copied from MacTutor Vol. 1 No. 4. 


;RESOURCE ATTRIBUTES 


SYSREF EQU 128 
SYSHEAP EQU 64 
PURGABLE EQU 32 
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LOCKED EQU 16 


PROTECTED EQU 8 
PRELOAD EQU 4 
CHANGED EQU 2 


RESOURCE FILE ATTRIBUTES 


READONLY EQU 128 
COMPACT EQU 64 
MAPCHANGED EQU 32 


;DITL TYPE EQUATES 


BUTTON EQU 4 

CHKBOX EQU 5 

RADIO EQU 6 

RESCTL EQU 7 

STATEXT EQU 8 

EDITEXT EQU 16 

ICONITM EQU 32 

QDPICT EQU 64 

USERITM EQU ð 

DISABLE EQU 128 

; WINDOW TYPES 

DOCBOX EQU Ø standard doc window 
ALERT EQU 1 jalert 

PLAIN EQU 2 jplain 

PLAINSHD EQU 3 ;plain with shadow 
NOGROWDOC EQU 4 ;doc window w/o grow box 
ROUNDBOX EQU 16 — ;rounded-corner window 


;(see IM for setting corner radius..) 


;CONTROL TYPES 


CBUTTON EQU ø Simple button 

CCHKBOX EQU 1 ,check box 

CRADIO EQU 2 ;radio button 

USEWFNT EQU 8 ,8dd to above to use 
; window's fonts 

CSCROLL EQU 16  ;scroll bar 


; IDENTIFICATION resource - needed for Finder to locate Icon 
RESOURCE 'WCA1' Ø ‘IDENTIFICATION’ 
DC.B AA1-61 
61: DC.B ‘Ver. 8.1 3/31/85' 
AAI: 


; BUNDLE resource 


ALIGN 2 
RESOURCE  'BNDL' ### ‘name’ [(attr)] 
DC.L 'WCA1' Signature 
DC.W 0,1 ,date (doesn't change) 
DC.L 'ICN''' ;icon mappings 
DC.W Ø ,number of mappings - 1 


DC.W 0,128 ,map Ø to icon 128 
DC.L 'FREF' ,FREF mappings 


DC.W 0 ,humber of mappings - 1 
DC.W 8, 128 ,nap Ø to fref 128 
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CONTROL resource 

; NOTE - although the assembler definition of this claims 
; that the “control type" field is a long word, IT LIES. 
; Control type is a 16-bit field!! 


. ALIGN 2 
RESOURCE  'CNTL' 8## 'name' [Cattr)] 
DC.W t ; top 
DC.W # ;left 
DC.W # ;bottom 
DC.W t ;right 
DC.W # ,initial value 
DC.W Ø ,visible (T/F) 
DC.W t ,nax value 
DC.W t ;hin value 
DC.W # ,control type 
DC.L 0 ,ref Con 
DC.B 62-e1 ,Vitle length Cat least 1) 
61: DC.B 'xxx' j title 
e2: 


,CURSOR resource 


„ALIGN 2 
RESOURCE  'CURS' ### 'name' (Cattr)] 
DC.L 8,8 j Ist 8 bytes of cursor 
DC.L #8 ;2nd 8 bytes 
DC.L #8 ;3rd 8 bytes 
DC.L #,# , Ath 8 bytes 
DC.L #,# j ist 8 bytes of mask 
DC.L 2,8 ; 2nd 8 bytes 
DC.L #8 ;3rd 8 bytes 
DC.L 8,8 , Ath 8 bytes 
DC.W #8 ;h,v of hot spot 


;FREF resource 
RESOURCE  'FREF' 88# 'name' [Cattr)] 
DC.B 'APPL',0,0,0 


, ICN® resource 

. ALIGN 2 

RESOURCE  'ICN'' 8## ‘name’ [(attr)] 
;there'd usually be an ‘include’ here... 


,MENU resource 

j 

; NOTE - the "enable field": bits are number right to left g- 
15. 

; Bit 1 is the first menu item. A "Ø" bit in the mask 
disebles 

; that item. I haven't tried it, but I think turning off bit 
8 of the 

, mask disables the entire menu.. 


„ALIGN 2 
RESOURCE 'MENU' ft 'name' [Cattr)] 
1b): DC.W 1 ,MENU ID 


59 


DC.W Ø width holder 


DC.W Ø ;height holder 

DC.L 9 ;Std menu pro holder 

DC.L $iFF ;enable all items 

DC.B e2-e1 ;title length Cin bytes) 
ei: DC.B 20 ;title Cthis is the apple) 


82: 


;MENU ITEM resource 


DC.B 9 ;item length 
DC.B 'xxx' jmenu item 
DC.B Ø ;ho icon 
DC.B Ø keyboard equivalent 
DC.B Ø marking character 
DC.B Ø ;style of item's text 
DC.B Ø JEND OF MENU ITEMS 
PATTERN stuff 
. ALIGN 2 
RESOURCE ‘PAT ' #88 ‘name’ [Cattr2] 
DC.L 9," sist, 2nd 4 bytes of pattern 
ALIGN 2 


RESOURCE 'PAT#' Sf ‘name’ [Cattr2] 
DC.W 8 ;* of patterns 
DC.L 8,8 ; 1st, 2nd 4 bytes of pattern 81 


; STRING resource 

ALIGN 2 

RESOURCE  'STR ' 3 'name' (Cattr)] 
DC.B @2-@1; text length 

@1:DC.B 'xxx' ;text 

62: 


;STRING LIST resource 
. ALIGN 2 
RESOURCE  'STRH' #88 ‘name’ [Cattr2] 


DC.W 8 ;count of strings 
DC.B @2-@1;text length - string #1 
@1:DC.B 'xxx' ;text 
82: 


label: ;REQUIRED REGULAR LABEL HERE! 


;WINDOW resource 


„ALIGN 2 
RESOURCE 'WIND' ### ‘name’ [Cattr)] 
DC.W # ; top 
DC.W 8 ; left 
60 


61: DC.B 
e: 


DC.w 8 ;bottom 

DC.W 8 ;right 

DC.W 3 ;window type 

DC.W 8 visible (T/F) 

DC.W 8 ;drew goAway (T/F) 
DC.L Ø ;refCon Cevaileble) 
DC.B 82-61 ;title length 

"xxx! title 


; -— Dialog / Alert / DITL are grouped together --- 


;DIALOG resource 


„ALIGN 
RESOURCE 


@1: DC.B 
e2: 


2 
'DLOG' 95 ‘name’ ([Cattr)] 
DC.W 8 ; top 
DC.W # ; left 
DC.W # ;bottom 
DC.W # ;right 
DC.W 8 ;window type 
DC.B * ;visible (T/F) 
DC.B Ø ; IGNORED 
DC.B #8 ;goAway flag (T=has close box) 
DC.B 8 ; IGNORED 
DC.L Ø ref Con 
DC.W 8 31D of DITL list 
DC.B 62-81 ;text length 
"Xxx" text 


;ALERT resource 


. ALIGN 
RESOURCE 


,UITL resource 


„ALIGN 
RESOURCE 


Tol: 


2 

"ALRT' #88 ‘name’ [Cattr2) 

DC.W # ; top 

DC.W 8 ; left 

DC.W 8 ,bottom 

DC.W 8 ;right 

DC.W 8 resource ID of DITL list 

DC.W 8 ;stages (see IM for details..) 
2 


'"DITL' #88 ‘name’ [Cattr)] 


DC.W # ;* of items - 1 
DC.L Ø ;handle holder 
DC.W 8 ; top 
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Macintosh Lisa 


Type BNDL 
, 128 
JEN4 Ø 
ICN# 
129 1 130 
FREF 
ð 131 1 132 
Type BNDL 
, 128 
JEN4 ø 
2 
ICN# 2 
8 129 
1 130 
FREF 2 
0 131 
1 132 
Type JEN4 = STR 
0 
This is for your own use 
Type FREF 
, 138 
APPL @ 
, 131 
SCRN 1 
Type ICN® = GNRL 
, 129 
.H 
0001 8000 0002 4000 
DOOF FOO OO0F Food 
Type ICN# 
, 129 
2 
£00 18000 


Comments 


Creator, Signature, Owner 
Finder Icon and Mask 

applic. is 129; document is 130 
File type 

APPL is 131; SCRN is 132 


Local ID Ø 

2 types follow 

2 licon lists 

local ID Ø goes with ICN! ID 129 


2 file references 
local ID Ø goes with FREF ID 131 


Creator name 
Local ID of Ø for ICN! and FREF 
Any text that you want 


File reference (file type) 
Resource ID = 139 
Application; local ID = Ø. 


Resource ID = 131 
Document file type; local ID = 1. 


Icon end Mesk for Finder 

Use IDs from 128 to 255 
Hexadecimal data will follow 

16 lines of 16 hex digits for icon 


16 lines of 16 hex digits for mask 


icon and mask follow 
32 lines of 8 hex digits for icon 
32 lines of 8 hex digits for mask 


Sota pare S RE Using CODE resources from Linker output ------------------------------ 


From Linker 
Use Demo9L.obj; start with CODE Ø 


e COCHE MES Controls, such as scroll bers, push buttons, etc. -------------------------_- 


Include TML 1: T 13 Tgpe CODE 
Demo9L , 0 
Type CNTL 
,401 


Vertical bar 
-] 416 273 432 
Visible 

16 

0 

8 78 35 


8 35 76 
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Control 

Resource ID 

Title; doesn't show on scroll bars 
top left bottom right (local coord) 
Can see it right away 

Scroll bar 

32-bit reference constant = 6 
Bininum maxiaum current 
minimum current maximum 
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) 
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----~------------------------------- (Cursor def inition 


Type CURS = GNRL 
,A01 

H 

2000 ... 0000 

FFFF ... FFFF 

0003 0003 


Type ALRT 
,95803 
70 131 190 381 
603 
F432 


Type DLOG 
,401 
About T13... 
38 12 326 500 
Visible NoGoAway 


501 


Type DITL 
,981 
9 


BtnI tem 
85 382 155 465 
Put Away 


ChkItem Disabled 
185 260 205 420 
Some words 


EditText Disabled 
185 10 205 245 
Modify these words 


IconI tem 
12 14 76 78 
257 


Picl tem 
35 25 98 110 
128 


Type CURS 
,401 
2000 . . . 0000 
FFFF...FFFF 

0003 0003 


Sene 


Use DITL number 603 


Use DITL 501 


Type DLOG 

, 401 
30 12 326 500 
Visible 1 NoGoAway 0 
501 Use DITL 501 
About Demo9.. 


Same 


BtnItem Enabled 


ChkItem Disebled 


EditText Disabled 


IconItem Enabled 


Use ICON ID = 257 


PicItem Enabled 


Use PICT ID = 128 


Dialog and Alert boxes 


Cursor 


Hexadecimal data will follow 
64 hex digits for cursor data 
64 hex digits for mask data 
top left Cy x) 


Alert box 
Resource ID 
top left bottom right (global) 


Stages list (stages 4321) 


Dielog window 

ID 

Dialog window title 

top left bottom right (global) 
or Invisible, or GoAway 

Dialog window type 

Dialog window reference constant 


1 = window type; Ø = ref constant 
Title 

Dialog Item List 

COptional) name, ID 

Number of items in list 

Push button, enabled 


top left bottom right Clocal) 
words to go in button 


Check box, disabled 

Includes check box and words 
Put to right of check box 
Editable text, with frame 
Up to 248 characters 

Icon, but no mask 


Icon scaled to fit this rectangle 


QuickDraw Picture (PICT) 
Picture scaled to fit this rectangle 
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RedioItem 
245 260 265 429 
1200 Baud 


ResCItem 

Ø 400 260 415 
512 

StatText 

218 18 238 245 
Cannot fix this 


User I tem 


Type ICON = GNRL 
,251 

.H 

OOFFAA11 


Type MENU 
,401 

M4 
About T13..^1 
(- 


Type PROC 
, 128 
MyProcedure 


Type STR. 
, 300 


This is a message 


Type STRE 
, 488 
2 


This is the first string 
Here is another string 


RedioItem Enabled 


ResCItem Enabled 


Use CNTL ID = 512 


StetText Enabled 


UserItem Enabled 


Icons for menu, dialog box, 


Same 


Type STR 
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Menu titles and items 


A single string Cuse GetString ROM call) 


A list of strings Cuse GetIndString) 


Redio button 
Button and words inside rectangle 
Words to right of radio button 


Scroll bar 


Fit in this rectangle 


Static text 
Word-wrepped inside rectangle 
Up to 248 characters 


User -def ined 


or in your program ------------------------ 


Icon, with no mask 

Use IDs from 256 to 511 
No .H for Lisa 

32 lines of 8 hex digits 


(Optional) name, ID 

Hex 14 = ACSII 20 = é 

Use ICON (256 + 1) = 257 on the left 
Disabled dotted line 


Procedure, such as CDEF, MDEF 
Resource ID 

filename for procedure (from Linker) 
Use blank after STR for Mac version 
Up to 255 characters 

List of strings 

Number so strings in the list 


Item 1 
Item 2 
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Graphics Lab: Asm 


Wizzo Shows Dissolve Effects 


Fair Warning 


Welcome to the second installment of the Graphic Lab. 
In this column we will explore the Mac's graphic capablilities 
and try to exploit them for all their worth. But I must warn 
prospective readers: This column is not for the so-called 
"power-users" or anyone else who bought their Mac to print 
out mailing labels. If you own a numeric keypad, this one 
isn't for you. This column is for people who'd rather watch a 
spaceship fly around on their screen than boot up Excel, 
given the choice. This column is for programmers who look 
forward to designing the title graphics for their applications, 
not the I/O drivers. This column is for those who never turn 
off the animation option in Switcher. So you've been warned. 
Everything beyond this paragraph will be pure frivolity. Let's 
go! 

Crimes of Graphics 


This second installment will deal with two crimes: one 
bad, and one good. First the bad one. Many of the people 
I've spoken with don't fully understand the potential of the 
Mac's graphics. They're blown away by some of the things 
they see, but they are convinced that the techniques are so 
involved that such feats are beyond their grasp. As a result, 
we haven't seen a lot of programs that push the Mac as far as 
they could. The good crime is one that we will commit, and 
one that will help us understand some basic principles of 
QuickDraw and graphics in general. 

This is the crime of theft. We are going to use a Desk 
Accessory called BitNapper published in last month's column 
to steal graphics from other applications. Then we will show 
some title animation using those stolen bit maps in a fun 
little animation demo called Wizzo. The BitNapper DA is 
listed in last month's Graphics Lab column. With it, we can 
cut BitMaps from any application that supports desk 
accessories, or we can use it to cut our own graphics from 
MacPaint. BitNapper saves the stolen BitMap to disk as an 
MDS source file which allows us to install them as resources 
into our applications much like we have done with icons and 
the icon converter program published previously in Vol. 2 
No.1 of MacTutor. 

To use the BitNapper, install it into the system file on 
the disk with the application whose graphics you want to 
pilfer. When the picture you want is on the screen, select the 
BitNapper. It will install its own menu into the menu bar. 
Now select "Steal Bits" from its menu. Position the upper 
left hand corner of the selection rectangle at the upper left hand 
corner of the BitMap you want to steal. Now drag down to 
the lower right hand corner. The BitNapper will invert those 
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bits within the selected rectangle. Release the button and the 
rest is self explanatory. The word constraint option will not 
be needed until later. It forces the selected BitMap to have left 
and right sides that coincide with word boundaries, which is 
sometimes useful. The BitNapper source, published last 
month, is also available on the source code disk #8 from 
MacTutor's mail order store. 


What the good book has to say 


Since we don't want to be complete outlaws, we will 
begin with some standard QuickDraw info taken straight from 
Inside Macintosh. The main QD data structure we will 
concern ourselves with is the BitMap. The BitMap is a 
rectangular arrangement of bits that describes some image. As 
a matter of fact, the Mac screen itself is a BitMap. Lets look 
at the structure of a BitMap. 


Figure #1 . 
The Structure of a BitMap 
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From figure #1 we can see that the actual bit image of 
the BitMap is not a part of the BitMap data structure. Rather, 
there is a pointer to the bit image. This is because bit 
images, such as that of the Mac screen, tend to be quite 
large. The way that BitMaps are defined allows several 
different BitMaps use the same bit image. This is useful, as 
many times BitMaps only differ in their bounds rectangles. 
Another item of note is the fact that the rowBytes value 
should always be even. The reason for this is shown in figure 
#2. It makes sure that the beginning of each row of data, or 
each scanline in the case of the Mac screen, occurs on a word 
boundary. This allows us to access the rows using word or 
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long sized instructions, which generally makes life simpler. 


ure #2 


Fi | 
Why rowBytes is Even 
Wrong way rowBytes - 29 


even 0 [ 1 ]-——[ 28 ] rows 
odd — row #2 


Right way rowBytes = 30 


even 0 [ 1]---[ 729] rows 
even xi row #2 


Peaceful coexistence 


Now that we have grabbed a chunk of graphics from our 
favorite application, what shall we do next? How do we get 
our application to access the BitMap with ease? The answer is 
to keep the BitMap in the resource fork of the application. In 
the resource file for our application we do something like: 


Resource 'GNRL' 135 
Include MyPicture. BMAP 


Where MyPicture.BMAP is the filename of the BitMap 
that you saved with BitNapper. The ID number can be 
whatever you want. Although I was tempted to use my own 
resource type, I decided to go by the book and use GNRL, 
which Apple considers legal. To facilitate the use of BitMaps 
in resources, I have written a few utilities which simplify 
things a bit. 


Figure #3 
How BitNapper Stores BitMaps 
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The first utility is a routine called GetBitMap, which 
loads a BitMap in from resources. It looks for an ID number 
in DO and returns a handle to the BitMap in A2. The handle 
allows the BitMap to be relocatable in memory, preventing 
heap fragmentation, but creating a problem. The way that 
BitNapper stores the data is shown in figure 43. Since our 
resource BitMaps can move around in memory behind our 
backs, we can never be sure if the basAddr pointer actually 
points to the bit image that follows it. 

The answer is a routine called LockBitMap. It locks 
the BitMap in memory and correctly sets the basAddr pointer 
according to the current position of the BitMap in memory. It 
takes a handle to the BitMap in A2 and returns a pointer to the 
BitMap in A3. Call LockBitMap just before you start using 
the BitMap. If memory is sparse, try to avoid allocating 
memory when there are locked BitMaps in memory. This will 
sidestep any heap fragmentation problems. 

After you are done working with a BitMap, call 
UnLockBitMap to allow the memory manager to relocate 
the BitMap as it sees fit. UnlockBitMap takes a handle to the 
BitMap in A2. But be sure to lock it down again before using 
It. 

The final routine is KillBitMap which, given a handie 
to the BitMap in A2, releases the memory occupied by the 
BitMap. If you don't want to kill your application as well, 
be sure not to use the handle after killing the BitMap. 


More than one way to skin a BitMap 


So we've stolen a BitMap, linked it into our resource 
fork, and are holding onto it by the handle. Now lets get it 
on the screen. This month's source code contains a couple 
examples of alternate ways to display a BitMap. 

These routines fall into two general categories: ones that 
employ patterns and ones that employ regions. Lets start with 
the pattern based copies. 


Wizzo Shows Bit Map Animation 


Our Wizzo program shows how we can read in the stolen 
bit maps created with BitNapper and display it on the screen 
with some dissolve effects. Wizzo has two pattern based 
routines for use in titling or other dramatic drawing of the bit 
map. The two examples of pattern based routines are FadeIn 
and FadeOut. 


Fadeln Shows Dissolve Effect 


FadeIn takes a BitMap handle in A2 and dissolves it 
Slowly onto the screen. The top,left corner of the destination 
is passed to FadeIn in D3,D4. First it locks the BitMap in 
memory. Then it makes a duplicate copy of the BitMap. 

In the main loop it copies the source BitMap to the 
destination BitMap (which is off the screen). It then sets the 
pen mode to notPatBic. In this mode, any time a pattern is 
drawn on the BitMap, it performs a logical AND with the 
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Figure #4 ar 
Effect of notPatBic painting 


on BitMaps 
paint 
pattern 


before painting 


after painting 


How the Dissolve effect is created in Fadein 


BitMap's current bit image. Figure #4 should make this more 
clear. The application has a table of 18 patterns of increasing 
darkness. In each iteration, a pattern is drawn over the entire 
duplicate BitMap, which at this point contains a copy of the 
source BitMap. Now we have a copy of the source BitMap in 
which only those bits set in our current pattern are set. I 
know...confusing, but the illustration is more clear. 

After this, the duplicate is copied to the screen. Then 
the process begins again with a slightly darker pattern, until 
finally we have an all-black pattern which copies the entire 
BitMap. FadeIn then unlocks the source BitMap and disposes 
of the memory it allocated for the duplicate BitMap. 

FadeOut does the opposite, as you may have guessed. 
Except that FadeOut only requires that you pass it a pointer to 
a rectangle in A4. It dissolves the bits enclosed within the 
rectangle on the screen. When it returns, the rectangle will be 
completely white. 

FadeOut simply sets the pen mode to notPatBic and 
repeatedly does a _PaintRect with successively lighter 
patterns. It works from the end of our pattern list to the 
beginning. 

These are fairly simple examples. Other possibilities are 
patterns of diagonal lines which move in barbershop-polelike 
fashion. Or perhaps altternating checkerboard patterns. 
Experiment with different variations. 
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A two-edged sword 


The next set of copy routines are region based. They 
facilitate the use of QuickDraw's ability to clip graphics to an 
arbitraty region. The problem that arises here is that 
QuickDraw, as David Letterman might say, is "just too darn 
powerful" It can do all sorts of fabulous calculations with 
regions, but it requires great sacrifices in speed. When any 
kind of region calculations are involved, QuickDraw bogs 
down. There are certain solutions, but in some cases it is 
better to write your own application-specific routines which 
are frightfully optimized for your specific case. Examples of 
this will come in future issues. Stay tuned, campers. 

Our region based routines, OpenRight and OpenOut 
repeatedy call _CopyBits with maskRgns that reveal more and 
more of the BitMap with each iteration. If you are not aware 
of it, CopyBits allows the caller to pass it a region to which 
the copied bits will be clipped. OpenRight starts with a 
rectangular region which clips all but the leftmost vertical row 
of bits, and expands the region to the right until the entire 
BitMap is copied. OpenOut starts with a region that clips all 
but the centermost bit of the BitMap and expands outward in 
all directions until the entire BitMap is copied. Both of these 
routines use the routine  RectRgn which creates a rectangular 
region, given a rectangle and a region handle. 


DC.B $00,$00,$B6,$F8,$00,$1E, $00, $00 
DC.B $00, $00, $00, $73, $00, $FO, $FF, $FF 
DC.B $FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF 
DC.B $FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF 
DC.B $FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF 
DC.B $FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF 
DC.B $FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF 
DC.B $FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF 
DC. E E E E E E $FF,$FF 
DC. : 

DC 


QJ QD OU w 0 0 


$DF,$FF, $FF, $FF, $FF. $FF. SFF’ $FF 
$FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF 
$FF,$FF,$FF,$FF,$FF,$FF,$FF,$FF 
$FF,$FF,$FF,$FF,$FF,$FB,$D0, $00 
DC.B $00,$00, $00, $00, $00, $00, $00, $00 
DC.B $00, $00, $00, $00, $00, $00, $00, $00 
.B $00, $00, $00, $00, $00, $00, $00, $00 
.B $00,$00, $00, $0B, $DO , $00, $00 , $00 


Fig. 5 Output of the BitNapper DA 
Formatted for an MDS Resource Included File 
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The saga continues... 


These examples were intended to give you a basic 
familiarity with the techniques involved with using the 
BitNapper and the sample routines. In the coming months we 
will explore other areas of interest, such as scrolling and 
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MaxEvents EQU 12 
DWindLen EQU $AA 
windowSize EQU $9C 
DiskEvent EQU 7 


animation techniques. I'm very interested in hearing from 
readers. If you have any suggestions or questions, drop me a 
line at: 


; size of a Dialog Record 
; Size of window data struct 


2556 Mabel St. shif tKey EQU 512; eventRec mask modif ier bits 
Berkeley, CA 94702-2141 jssssss= Start of Main Program zzzzzzzzzzzzizzz 
Figure 5 shows the MDS text file format that BitNapper | BedPtr: ^ Debugger ;Should never get here. 
creates for us. As you can see, this is all ready to be included START: 
in our resource file. Figure 6 shows the bit map example used MOVEM.L  D0-D7/A9-A6,-(SP)  ;The routine 


by Wizzo. Of course with any animation example, the real LEA SaveRegs(A5), Ad ;which saves the registers 
action is over by the time we get a screen shot. Perhaps next MOVE .LA6, CAB) 


MOVE .LAT, 4CAB) 
time we will look at exploding and imploding BitMaps...see i 


you then. j======== Initialize the ROM routines ============= 
i PEA -4(452;0D Global ptr 
MacTutor BitMap Demo _InitGraf ;Init QD global 

-InitFonts ;Init font manager 
-InitWindows ;Init Window Manager 
-InitMenus ;Guess what...you got it! 
CLR.L -CSP) ;Standard SysErr/DS dialog 
-InitDialogs ,init Dialog Manger 
-TEInit ;Init ROM Text edit 


MOVE.L"AllEvents,DO ;And flush ALL previous 


-FlushEvents ,events 
-InitCursor ;Get the standard arrow 
;7222---- Begin our routine processing ========== 
MOVE #128 DO ;get bitmap #128 
cbe lesend lives ON... BSR GetBitMap ;from resources into A2 
' ; This is where the BitMap routines are called 
Fig. 6 Output of our Wizzo BMTest: 
PEA Screen 
program after Fadein PEA White 
Animation. -FillRect 
MOVE $2,-CSP) ;Get Geneva 12 
-TextFont 
MOVE #12,-CSP) 
; © BitMap Demo #1 e _TextSize 


CenterMacTutor BitMap Demo, 256,50 


MOVE 1102,03 
INCLUDE MacTraps.D MOVE 1140,04 
BSR FadeIn 


; 9 1986 by Chris Yerga for MacTutor 
,top coordinate 
;left coordinate 
;FadeIn (Note handle in A2) 
; Declare external labels 

LEA TempRect(A5), A4 
XDEF START BSR FedeOut 


;,get tempRect 
jand erase its contents 


MACRO Center  String,MidPT,Y = MOVE 100,03 ; top coordinate 
MOVE #14,D4 ; left coordinate 
CLR.W -CSP) ; INTEGER width of string BSR OpenRight ;OpenRight 
PEA |  '(String)' 
-StringWidth LEA TempRect(A5),A4 ,get tempRect again 
CLR.L D3 ; Clear high word of 03 for DIVU BSR FadeOut jand erase its contents 
MOVE .WCSP)+,D3 ; Get the width Cin pixels) in D3 
DIVU "2 03 ; Divide by 2 MOVE 3 5100,D3 ; top 
MOVE .L# (MidPT) ,D4 MOVE #140 D4 “left 
SUB.W D3,D4 ; 103-Cwidth/2) to center text BSR OpenOut ;OpenOut 
MOVE .WD4, -CSP) ;Push the X coordinate 
MOVE .W* (Y), -CSP) ;Push the Y coordinate BSR BlackOut 
-MoveTo ;Position the pen 
BSR GetEvent ;check for any events 
; insi: MOVE Event(A5), DØ 
PEA — "Gtring) CMP #8, DB  ;do we have an event? 
-DrewString BEQ BMTest ^ ;no, keep going 
| ;End of Macro 
Adios: 
j========= Local Constants ==sss=ssssssss=== LEA SaveRegs(A5), AØ ;yes prepare to exit 


MOVE .L CAO), A6 


AllEvents EQU MOVE .L4CA02,A7 


$0000FFFF ; Mask for FlushEvents 
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MOVEM.L (SP2* ,D0-DT /A0-A6 


RTS 
; zzzzsz2zz2-2z Subroutines zzzzzzzzzzzzzzzzzz 
GetEvent: 
CLR -(SP) ;,returned event 
MOVE "AllEvents, -CSP) ;mask all events 
PEA EventRecord(A5) ; event record block 
-GetNextEvent ;go check the mouse 


MOVE (SP)+,D8 jget event result 
MOVE DØ, EventCA5) ,save event in our global 
RTS ;return 
; =======These are the general BitMap utilities ====== 
GetBitMap : Reads a BitMap in from resources 


f on entry : DØ = BitMap resource ID 
; returns a handle to the BitMap in A2 


GetBitMap: 
CLR.L -CSP) jroom for Handle 
MOVE.L®'GNRL',-CSP) ;the resType 
MOVE DØ,-(SP) ;resID 
-GetResource 
MOVE .LCSP)+, A2 jget the handle 
RTS 


; LockBitMap : Locks the BitMap in memory and calculates the 


BasAddr field so that it's ready to use. 


, 
on entry : A2 = handle to BitMap 
; returns a pointer to the locked BitMap in A3 


LockB i tMap: 
MOVE.LA2,A0 ,copy handle 
-HLock ;lock it 
MOVE .LCA2),A3 ;get pointer 
ADDA #14,A3 ¿point to bit image 


MOVE.LA3,-14(A3) ;set basAddr field 
MOVE .LCA2),A3 ;get pointer 
RTS 


; UnLockBitMep : makes the BitMap relocatable. Called 


whenever processing has been finished on a bitMap 


that will be used again so that Heap Fragmentation 
i doesn't occur. 
; on entry : A2 = handle to bitMap 
UnLockB i tMap: 
MOVE .LA2, A ;copy handle 
~HUnLock junlock it 
RTS 


; KillBitMap : Does what it says 
on entry : A2 = handle to bitMap 


BE SURE NOT TO REUSE A DEAD BITMAP! DANGLING 
POINTERS! YOUR APPLICATION WILL DIE ALSO! 


" 
) 
) 
" 


KillBitMap: 

MOVE .LA2, Að ;,copy handle 

-DisposHandle 

RTS 
; ====These are the sample BitMap display routines ===== 
; FadeIn : Displays the BitMap with a reverse dissolving 


effect 


2 


; On entry : A2 = bitMap handle 
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D3,D4 = top,left coordinates of display rect 


FadeIn: 


81 


MOVE .LA2, AQ ;copy handle 


-GetHandleSize ;get handle size 

-NewPtr , Clear ,;allocate an equal sized block 
MOVE .LA®,A4 ;copy pointer 

BSR LockB i tMap ;lock and init bitMap 

LEA TempRect(A5), Ad jget ptr to dest rect 
MOVE D3, CA®) ,copy top 

MOVE .D4,2(A0) ;copy left 

ADD 19CA3),D3 ;calculate bottom 

MOVE .D3,4CA0) 

ADD 12€A3),D4 ;calculate right 


MOVE D4,6CAQ) 

MOVE .L4CA3),4CA4) 
MOVE .L8CA3),8CA4) 
MOVE 12(A3), 12(A4) 
LEA 14(A4), AG 
MOVE .LAØ, CA4) 

MOVE .LA4, -CSP) 


jcopy the header info 


;Set basAddr 
;the dest bitMap 


-SetPBits 

MOVE #15,-CSP) ;notPatBic mode 
-PenMode 

MOVE #8,D3 ;pat counter 


MOVE .LA3, -CSP) 
MOVE .LA4, -CSP) 
LEA 6(A3), AG 


;source BitMap 
,dest BitMap 
,get pointer to bitMap bounds 


MOVE .LA®, -CSP) ;SourceRect 

MOVE .LA®,-CSP) ;destRect 

MOVE %@,-CSP) ;srcCopy 

CLR.L -CSP) 

-CopgBi ts 

LEA PatList, Ag ,ptr to patterns 
MOVE D3,DØ ,copy pattern index 
MULU "8 DO ;offset to pattern 
ADDA DO, Ad 

MOVE .LA®, -CSP) point to pattern 
_PenPat 

PEA 6CA4) ;BitMap bounds 
-PaintRect paint the rect 


MOVE .LA4,-CSP) 
MOVE .LCA5), Ad 


;source BitMap 


PEA $FFFFFF86CAg) ;dest BitMap (GrafPort) 
PEA 6CA4) ;SourceRect 
PEA TempRect(A5) ,destRect 
MOVE  "0,-CSP) ,srcCopy 

CLR.L -CSP) 

—CopyBi ts 

ADDQ #1,D3 ;next pattern... 
CMP #19, D3 ; done? 

BNE e1 ;not done.. 
MOVE.L CA52,A0 ,restore screenbits 
PEA $FFFFFF86CA0) 

-SetPBits 

MOVE .LA4,A0 ,free up memory 
-DisposPtr 

BSR UnLockB i tMap 

RTS 


; FadeQut : Erases the contents of a rect with a dissolve 


) 


, On entry : A4 = pointer to rect to be erased 
FadeOut 
MOVE #15,-(SP) jset pattern mode to notPatBic 
-PenMode 
MOVE #18,D3 ;init pattern counter 
@1 LEA PatList, AQ ;ptr to patterns 
MOVE D3,DØ ;copy pattern index 
MULU "8 DO ;offset to pattern 
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ADDA DO, AB PEA RgnRect(A5) jand the rect 


MOVE .LA®,-CSP) ;point to pattern -RectRgn 
~PenPat MOVE .LTempRgn(A5),A4 ;copy rgnHandle to A4 
MOVE .LA4,-CSP) ;BitMap bounds BSR ShowB i tMap 
-PaintRect ,paint the rect ADD 81,RgnRect*4CA5) ,extend the bottom 1 pixel 
ADD #1,RgnRect+6(A5)  ;extend the right 1 pixel 
TST D3 jare we done SUB 8],RgnRect(A5) ;extend the top 1 pixel 
BEQ 82 jyes SUB R1,RgnRect+2(A5) = ;extend the left 1 pixel 
SUBQ #1,D3 ;decrement the pattern number MOVE  12(A32,D0 ;get right edge of BitMap 
BRA e1 ; loop ADD D4,D8 ;calculete width 
@2 RTS CMP RgnRect+6(A5), D8 shave we extended the rect 
jall the way there? 
; OpenRight : Opens the BitMap on the screen from left to BGE e1 jno. ..keep going 
right MOVE 1ØCA3),DØ ;get bottom of BitMap 
; ADD D3,D0 
, On entry : D3,D4 = top, left of screen destination CMP RgnRect+4(A5), DØ jare we done? 
; A2 = handle to bitMap BGE 81 ;no... 
MOVE .L TempRgn(A5), -CSP) 
OpenRight -DisposRgn 
BSR LockB i tMap j lock the handle in memory RTS 
CLR.L -CSP) ,room for rgnHandle 
-NewRgn ; ShowBitMap : Displays the BitMap on the screen 
MOVE .LCSP)+,TempRgn(A5)  ;save the handle ; 
MOVE  D3,RgnRect(A5) ,copy top of bounds , on entry : D3,D4 top, left of screen destination 
MOVE D4,RgnRect+2(A5) ,copy left of bounds : A4 = maskRgn or NIL 
MOVE 03,08 
ADD 10 CA3),D0 ;calc bottom ShowB i tMap 
MOVE .DO,RgnRect*4(A5) BSR LockB i tMap ;lock it in memory 
MOVE D4,RgnRect+6(A5) ;,meke it 1 pixel wide LEA TempRect(A5),A0 ,get ptr to dest rect 
MOVE 5D3,CA0) ,copy top 
MOVE D4,2CA0) ;copy left 
61 ADD 81, RgnRect*6(A5) ,extend right edge 1 pixel MOVE D3,DØ 
MOVE .LTempRgn(A5),-(SP)  ;push rgnHandle MOVE D4,D1 
PEA RgnRect(A5) ;push the rect ADD 1ØCA3), DØ calculate bottom 
RectRgn ,make it a region MOVE .D0,4CA0) 
MOVE .L TempRgn(A5),A4 ;copy rgnHandle to A4 ADD 12(A32,D1 ;calculate right 
BSR ShowB i tMap MOVE D1,6CAQ) 
ADD 81 RgnRect*2(A5) ,extend left edge 1 pixel 
MOVE  12CA32,00 ,get right edge of BitMap MOVE .LA3, -CSP) ,Source BitMap 
ADD D4,D0 ;calculate width PEA thePor tCA5) ;get GrafPtr 
CMP RgnRect+6(A5),D8  ;have we extended the rect -GetPort 
jall the way there? MOVE .L thePor tCA52, A0 
BNE e1 jno.. .keep going PEA 2(A0) ,dest BitMap CGrafPort) 
MOVE.LTempRgn(A52,-CSP)  ;free up memory PEA 6CA3) ;sourceRect 
-DisposRgn PEA TempRect(45) ,destRect 
RTS MOVE #Ø,-(SP) 
MOVE.LA4, -CSP) 
; OpenOut : Opens the BitMap up from the center outward -CopyB i ts 
; RTS 
, On entry : D3,D4 = top, left of display rect 
: A2 = handle to bitMap ; BlackOut : Matthias Jabs would be proud... 
OpenOut BlackOut : 
BSR LockB i tMap ;lock the handle in memory MOVE #8,-(SP)  ;set the pattern mode to patCopy 
CLR.L -CSP) ,room for rgnHandle -PenMode 
-NewRgn MOVE  "2,D3 ;init pattern counter 
MOVE.LCSP)+,TempRgn(A5)  ;save the handle 81 LEA PatList,AQ ,ptr to patterns 
MOVE D3,DØ ,copy pattern index 
MOVE D3,DØ ,copy top MULU #8 DO ;offset to pattern 
ADD D3,D9 multiply by 2 ADDA DO, Ag 
ADD 1ØCA3), DØ ,add offset MOVE .LA£, -CSP) ,point to pattern 
EXT.L DØ ,extend to 32 bit precision -PenPat 
DIVU #2,DØ ;find center PEA Screen ; the whole screen 
MOVE D4,D1 ,copy left -PeintRect ,paint the rect 
ADD D4,D1 ;multiplg by 2 
ADD 12€A3),D1 ,add offset CMP #18 D3 jare we done 
EXT.L D1 ,extend precision BEQ e2 ;yes 
DIVU 82,01 ;find center ADDQ #1,D3 ,decrement the pattern number 
MOVE D®,RgnRectCA5) ;top of the rect BRA e1 ; loop 
MOVE Di,RgnRect*2(A45) ;left @2 RTS 
ADD *1,D0 
MOVE D®,RgnRect+4(A5) X ;bottom ,=====5=== Program Variables =========s=s====== 
ADD #1,D1 
MOVE Di,RgnRect*6(A5) X ;right SaveRegs: DS.L 2 ;For saving the SP etc.. 
61 MOVE.LTempRgn(A5),-CSP)  ;push the rgnHandle thePort : DS.L 1 
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TempRect: DS.W 4 
RgnRect: 
TempRgn: DS.L 1 


EventRecord: DS.B 
Event: DS .W 


DS.W 4 


16 ;event record block 
jsave event number 


BlackPat: DC.L $FFFFFFFF, $FFFFFFFF 
D 


White: 
GrayPat: 


Screen: DC .W 


PatList: 


jto type this in, 


DC.B 0,0,0,0,0,0,0,0 


DC.B $28, $28, $20, $20, $02 


DC.B $00, $08, $00, $08 
DC.B $00,$00,$00,$02 
DC.B $20,$00,$00,$08 
DC.B $00,$40,$00,$02 
DC.B $24,$00,$00,$08 
DC.B $00,$42,$00,$02 
DC.B $24,$80,$08,$88 
DC.B $00,$42,$20, $02 
DC.B $26, $80,$28, $A8 
DC.B $00, $42,$00, $82 
DC.B $26, $80,$28,$A8 
DC.B $00, $4E, $20, $82 
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C.L 0,0 
DC.B $55,$44,$55,$44,$55,$44,$55, $AA 
0,0,342,512 


DC.B $46,$80,$2E,$40 
DC.B $01, $4E, $21, $82 
DC.B $A6, $C0,$2E, $A9 
DC.B $01, $5E, $21, $86 
DC.B $A6,$C0,$2E, $A9 
DC.B $23, $5E,$25,$C6 
DC.B $A6,$C0,$2E, $40 
DC.B $23,$5E,$25,$C6 
DC.B $AE,$01,$2E, $AD 
DC.B $23, $0F, $25, $06 
DC.B $AE,$D1,$AE, $AD 
DC.B $23, $0F, $E5, $06 


;Pattern data for fade routines...if you have 
you have my sympathy 


DC.B $AE, $07, $AE, $FF 
DC.B $6F, $0F, $65, $0F 
DC.B $AF, $F7, $8E, $FF 
DC.B $6F, $0F, $F5, $FF 
DC.B $AF, $F7, $8E, $FF 
DC.B $7F,$0F,$FD, $FF 
DC.B $EF, $FF, $FE, $FF 
DC.B $FF, $0F, $FD, $FF 
DC.B $FF,$FF, $FF, $FF 
DC.B $FF, $FF, $FF, $FF 


ISTART 
/Output WizzoGraf 
] 


Wizzo 
/Resources 
WizzoRes 


/TYPE 'APPL' WIZZ' 
$ 


; This is how you get your BitMaps 
; in your resource fork 

.Align 2 

Resource 

'GNRL' 128 ‘test BitMap' 
INCLUDESpinalTap.BMAP 
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Assembly Language Lab 


CMD-Shift-3 Patch for the New ROMS 


Menu Snapshots with the new 
ROMs 


€ File E 


As was described in the July 
MacTutor, attempting to take a screen 
dump with a menu pullled down on a 
machine with the 128K ROM results in 
the menu snapping up before the dump 
is taken. Also, on both old and new 
ROMS, pulling down a menu results in 
the Alarm clock (and any other desk 
accessories which require periodic 
updates) freezing, because no call is 
made to SystemTask by the Menu 
Manager. This short patch fixes both of 
these problems. 


Edit 1.54 


IN 


letter format 


First, we need to patch the menu definition 0 resource in 
the system file. To do that, start up ResEdit and open the 
system file. Select MDEF 0 resource. Double-click on it and 
insert the following code at the beginning of the resource: 


9EFC 0012 3F3C 0008 
486F 0004 A970 DEFC 
0012 A9B4 


You may want to set the system heap flag as well to 
improve performance. This will cause it to be loaded once by 
the Finder and then remain on the system heap for subsequent 
applications. 

Now close and save the system file. Assemble and link 
the INIT resource at the end of this article, and paste it into 
your System file. (Note: Make sure that the ID of this INIT, 
(17), does not duplicate that of an existing one-change if if 
necessary.) When you run an application, you will find that 
pressing Command-Shift-3 with a menu pulled down results 
in a screen dump being taken immediately, without waiting 
for the mouse to be released. This permits multiple snapshots 
to be taken from the same menu without having to pull it 
down each time, a boon when documenting a long menu. 
Also, desk accessories will no longer freeze when a menu is 
down, although they will still freeze when the cursor is in an 
unused part of the menu bar. 


How it Works 
This is the source code for this patch above: 
SUBA.W 


#18,SP  ;stack space for evt record, result 
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t View 


MacD 


tutor format 2 


Harvey Grosser 
Oakland, CA 


Sep 


Asm Link 


Special 


PageMaker 1.2 logos2 


article format — MDEF ROM patch 


DUE EREDEREMERS Oe iC RSET ARCA 
tee rece a 


Fig. 1 It Works Again on a Mac Plus! 


MOVE.W #8,-(SP) ;keydown event mask 

PEA 4(SP) ;address of evt record VAR param 
. GetNextEvent 

ADDA.W &18,SP  ;discard function result & event rec 
. SystemTask ;allow DAs to work 


Since the menu definition function is executed repeatedly 
while a menu is pulled down, this results in calls to 
GetNextEvent with an event mask which permits it to take 
key down events from the system event queue. When it sees 
one of these, it executes the appropriate FKEY routine if a 
Command-Shift-number key combination was pressed. The 
call to SystemTask permits desk accessories to run. The 
INIT routine is necessary because the new resource manager 
uses the MDEF 0 in ROM rather than the one in the System 
File. (See the Aug. '85 issue of MacTutor for info on the 
INIT resources.) The patch functions by setting 
ROMmapInsert to 0 before every call to GetResource 
when the type asked for is MDEF or FONT. (This permits 
editing the Chicago font, some characters of which I consider 
really bad.) It is necessary to patch GetResource directly 
like this because the Menu Manager always sets 
ROMmapInsert to TRUE before making the call. I would 
really appreciate it if someone out there could give the exact 
meaning of the individual bytes at $B9E (ROMmapInsert) 
and $B9F (TempResLoad); Apple's Tech Note #57 is rather 
vague on this. 
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; MDEF INIT . ASM 
; place this INIT in system file 
; to fix cmd-shift-3 bug 


Place this patch in MDEF 6 
resource Cat beginning), in 
your system file: 


SEFC 0012 3F3C 0008 
486F 0004 A970 DEFC 
0012 A9B4 


Patch meaning: 


SUBA.W — *18,9P 
MOVE.W — "8, -CSP) 
PEA 4CSP) 
_GETNEXTEVENT 
ADDA.W #18, SP 
_SYSTEMTASK 


we We We We We We We We We We We We We We We We We 


INCLUDE MACTRAPS .D 

GetResource equ $4940 — ; trap address 

ROM85 equ $28E ;new ROM= $7FFF 

RomMap Insert equ $B9E 

RESOURCE '‘INIT' 17 'MOEF Init' $50 ;SysHeap+locked 


start: 
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BRA .W af ter 


patch: 

CMPI.L — *'MDEF', 6CSP) ;check type 

BEQ.S e1 ,for MDEF or FONT; 

CMPI.L *'FONT', 6CSP) ;if not, 

BNE .S jump ;don't change map 
e1: 

CLR.W ROMmapInsert 
jump: 

JMP $ 12345678 ;filled in by init routine 
efter: 

LEA start, Ag 

-RecoverHandle ;handle to proc 


TST.W ROM85  ;new roms? CTFFF) 
BPL.S newROM ;yes, go for it 


-DisposHandle jno, forget it 
RTS jand exit 
newROM: 
MOVE.L — fefter-stert,DO ;get our size 
-SetHandleSize jchop off init routine 


MOVE .W ®Ge tResource, DØ 
-GetTrepAddress  ;addr of GetResource 


LEA jump+2,A1 ,peste it into patch 
MOVE.L A0, CA1) patch it 
LEA patch, AØ 


MOVE.W  #GetResource, DØ 
-SetTrapAddress  ;install patch 


RTS ey! 
END 
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Assembly Language Lab 


Create a Tic Tac Toe Game! 


While reading MacTutor and learning how to program in 
68000, I decided to try and write a simple game. I wanted 
something that was simple enough so that I could concentrate 
on the coding of it rather than the logic of it. Tic Tac Toe was 
the obvious choice. It would let me try using menus, 
windows, dialogs and simple graphics. After the initial game 
was written, I added some other features just for the sake of 
making the game a little more interesting. Then I added two 
text manipulation effects to take some of the boredom out of 
the "About" dialog. The result is a program that is more 
complicated than the average Tic Tac Toe program, but 
(hopefully) simple enough so you can follow the code with 
relative ease and learn something from the techniques and 
routines used in it. 

The files used are "TicTacToe.asm", a resource file 
"TicTacToe rsrc.asm" that contains two icons used in the 
" About" dialog, two text effects routines "GrowText.asm" and 
"SnakeText.asm", and the link file "TicTacToe.link". I have 
found that building a library of common subroutines (like 


Mike™ Scanlin 
World Traveler 


TicTacToe 
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Fig. 1 Our Tic Tac Toe Game! 


use TextEdit so that desk accessories and dialogs will work 
correctly. 

After the basic initialization, all menus, windows and 
dialogs are created. The reason for creating all of the windows 


and dialogs in the beginning of the program is twofold. First, 
because it's nice having them all together in the source code 
for debugging purporses. Secondly, and more important, it 
helps to keep the heap from becoming fragmented if they are 
all created one after the other. This technique is probably best 
used for static data structures that are needed throughout the 
entire program (e.g. global variables). On larger programs 
with lots of windows and dialogs, it is probably not a good 
idea to make them all at once (due to RAM limitations). The 
remainder of the initialization and the main event loop 


GrowText and SnakeText) that can be linked together and used 
in different programs is incredibly useful. After 5 years of 
6502 programming on the Apple ][ without this feature, I 
have learned to love the Macintosh Linker. The Tic Tac Toe 
program that follows could be split up into even more 
subroutine files if desired. 


The Program 


The program starts off by initializing all routine 
manangers that it will be using. I should point that there is a 
"resume" procedure pointer passed to _InitDialogs (instead of 
the typical nil pointer). The consequence of this is that if a 
serious system error should occur, the "resume" button will 
not be greyed and if you click on it control will be passed to 
the "resume" procedure. In my case, all the resume procedure 
does is jump to the Finder (via _exitToShell). I find this quite 
helpful when developing a program because it is much quicker 
than rebooting the system. Of course, if the program messed 
up RAM in some way it could be a big mistake to jump to 
the Finder and continue work as if all was normal. But due to 
the nature of the program I was writing (wasn't dealing with 
disk IO), I decided to use it anyway (and had no problems). 
Use this with discretion and ALWAYS keep backups. If you're 
at all unsure (or nervous) about the possible effects of your 
program, then don't use this method (use "CLR.L -(SP)" in 
place of "PEA resume" to push a nil pointer. That will grey 
the "resume" button and force a restart if you get a serious 
System error) The next thing called is _TEInit. As Inside 
Macintosh says, it should be called even though you may not 


© The Complete MacTutor, Vol. 2 


(GetEvent) should be straightforward. It is very similar to 
previous programs published in MacTutor. 


The Dialogs 


All of the dialogs use a routine called CenterString. Its 
function is to calculate the offset from the left edge of a 
window needed to center a string in a window, given the width 
of the window (the windowWidth variable) and a pointer to the 
string. The algorithm is fairly obvious: subtract the length of 
the string (found from _StringWidth) from windowWidth and 
divide by two. This value is returned in DO and is used as the 
horizontal value for the | MoveTo called just before 
_DrawString. 

Additionally, the "About" dialog uses the two routines 
GrowText and SnakeText. GrowText starts out by drawing the 
string at a textSize of 1 point and then redraws it at 2 point, 
etc., up to 12 point (erasing the previous string with 
_eraseRect just before drawing the new string) so that it looks 
like the string is growing. SnakeText is rather more 
complicated, but works in a similar manner. It doesn't really 
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look like a snake, but for lack of a better name that's what it 
is called. The best way to understand what it is doing is to 
watch it perform a couple of times. Basically, it is redrawing 
characters at different textSizes until they're all at 12 point. By 
studying the commented source code, you should be able to 
get some idea of how it works. But you don't need to 
understand how it works to use it within your own programs 
(just be sure you set up the input registers correctly). I should 
mention that the rectangle that you pass a pointer to must be 
tight fitting around the text it is to draw (i.e. no extra white 
space around the top,left, or bottom -- the right side isn't too 
important). If it isn't, the routine will still function, but it 
may not look too pretty on the screen (like a lot of overdrawn 
or partially overdrawn characters). The method I used to find 
the correct dimensions of the rectangle is to draw the string 
where I wanted it and then use _FrameRect until I found the 
smallest possible rectangle that would enclose all of the text. 
It will probably take a little trial and error to get the 
dimensions perfect, but it's important. 

The DefaultOutline subroutine is used to draw the 3 pixel 
wide oval around the "OK" button in the dialogs in the 
standard way. It is worth pointing out that anything you want 
in a dialog box that isn't in the dialog's item list has to be put 
in the dialog box before calling _ModalDialog (when you call 
_ModalDialog, it draws the things that are in the dialog's item 
list). So the oval around the "OK" button is actually drawn 
before the button is drawn by  ModalDialog. This is also true 
for any dynamic text (or special effects like GrowText or 
SnakeText) that you want to have in the dialogs. 


Game Logic 


Every time you select "New Game" from the "Game" 
menu, the computer randomly decides who goes first. If you're 
looking at a blank board after you have selected "New Game" 
then you go first, otherwise you'll see a square somewhere (the 
computer's first move). The player is always circles, the 
computer is always squares. The "Reverse Positions" option 
merely switches all circles for squares and squares for circles - 
- it does not change the order of turns or who is what piece. It 
was included as an option mainly because it was easy to code 
(besides, it does add a little to the interest of the program). It 
is only enabled when a game is in progress. 

If the difficulty is set on "easy" then the computer will 
always move randomly (which gets boring after about 1 
game). The "hard" difficulty should be called "not quite so 
easy, but not very difficult either" but that is a bit of a long 
name for a menu option. Face it, this is not a difficult game 
to play, theres not a whole lot you can do to make the 
computer (or anyone else, for that matter) play more 
intelligently. When set on "hard" it makes three checks for 
intelligent moves before it decides to move randomly: (1) 
checks if the computer can win in the next move, (2) checks if 
the computer can block a player win in the next move, (3) 
checks if the middle square is taken. The "cheating" options 
were added for fun. As the dialog says, anyone who is allowed 
to cheat (player or computer) is allowed to move on any 
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Fig. 2 With some nifty dialog ‘about’ boxes... 


That's nice ») 


square, even if someone else is already there. As far as the 
coding of this is concerned, all it amounts to is bypassing the 
usual checks for valid moves. 

If there is a mouseDown event anywhere in the game 
window, the point is checked to see if the player clicked in one 
of the nine squares. The coordinates of the click are first 
converted into local coordinates by calling _GlobalToLocal 
and then checked to see if the point is in any of the nine 
Squares by calling _PtInRect. The coordinates of the nine 
Squares are in stored in the table BoardLocs. These coordinates 
are used as dimensions for drawing the squares and circles 
(with _FrameRect and _FrameOval) as well as checking for 
validity of mouseDown events. 


Miscellaneous 


The "Show/Hide scores" menu option was included to 
demonstrate how to change menu items. All that is needed is 
to set up the parameters on the stack and call _SetlItem. 
Likewise, the checking and unchecking of the difficulty setting 
and cheat settings can be accomplished with calls to 
_ChecklItem. 

One thing I learned while writing this program (after many 
headaches) is that any variable declared with the "DS" (Define 
Storage) declarative will have to be referenced with address 
register AS. This is not true for variables declared with the 
"DC" (Define Constant) declarative. For instance, if ShowFlag 
is declared "ShowFlag DS 1" it will be referenced as " MOVE 
ShowFlag(A5),DO" but if it is declared "ShowFlag DC 1" it 
will be referenced as "MOVE ShowFlag,DO". This is because 
all storage declared with DS is put in the application globals 
space (pointed to by A5 when your program starts) while all 
storage declared with DC stays within the program code 
segment (addresses filled in by the Linker). If you use both 
types of declarations (DS and DC) in your programs, as is 
done in this one, it is critical to pay attention to which is 
which and use the correct type of reference or you will end up 
with random results. 

As was mentioned above with respect to SnakeText and 
GrowText, the routines presented here can be used as part of 
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your own programs. The RandomBounds routine (combined 
with its initialization of randSeed in the beginning) is a good 
way to get bounded random numbers into your assembly 
language programs. It returns a positive integer in the range 1 
to DO, where you set DO before calling it. The CenterString 
and DefaultOutline routines should be useful, too. 


; GrowText 4 March 1986 


; print a text string starting at 1 point up to 12 point, 

, centered in a rectangle (horizontally, not vertically). 

; the string gets a little bigger each time through the loop. 
; inspired by Lynn Bond, who gets a little bigger each time 

; She eats a pound of M&M's. 


.TRAP _EraseRect $A8A3 
.TRAP _TextSize $A8BA 
.TRAP _MoveTo $4893 

. TRAP -DrawString $4884 


Xref — GrowText, CenterString,windowWidth 


right EQU 6 
left EQU 2 
GrowText 


; before calling, user should push the following onto the 
Stack: 
; Cin this order) 


f address of string to print 
; addr of rect that encloses the string 
j vertical height to print string 


é 
,Save return address 

MOVE.L (SP)+,returnAddress(A5) 
,get parameters 

MOVE (SP )+, vPosition(A5) 

MOVE.L (SP)+,rectPointer(A5) 

MOVE.L (SP2*,stringPointer(A5) 
,Seve windowWidth 

MOVE windowWidth(A5),-CSP) 
,Sset up windowWidth and leftEdge so we can draw some 
; centered text 

MOVE.L rectPointer(A5),AQ 


MOVE rightCA2), windowWidth(A5) 
MOVE lef tCA®), DØ 
MOVE DO, lef tEdgeCA5) 
SUB DØ, windowWidth(A5) 
;,init textSize to 1 
MOVE 81, textSizeCA5) 
e1 MOVE.L rectPointer(A5),-CSP) ;erase old string 
-EreseRect 
MOVE textSizeCA5), -CSP) 
-TextSize 
MOVE.L stringPointer(A5), AQ 
JSR CenterString 
ADD lef tEdgeCA5), DØ 
MOVE D£,-CSP) ;h 
MOVE vPositionCA5),-(SP)  ;v 
-MoveTo 
MOVE.L stringPointerCA5),-CSP) ;draw new string 
-DrewString 
MOVE 832000 ,DØ ,delay 
@2 DBRA DØ, @2 
ADDQ #1, textSizeCA5) ,inc textSize for 
,hext iteration 
CMPI #13, textSize(A5) 
BNE ei 
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restore windowWidth 
MOV CSP )+, windowWidth(A5) 
MOVE.L returnAddress(A5), -CSP) 


RTS 

; global variables 

textSize DS 1 
vPosition DS 1 
rectPointer DS.L 1 
stringPointer DS.L 1 
lef tEdge DS 1 
returnAddress DS.L 1 
; SnakeText — 22 February 1986 


; Do a neat special effect with a String of chars. Print each 
; char in string 1 to 11 times (currently set at 6), from 2 


p 
; to 12 pt so that it looks really cool. 


.TRAP  .EraseRect $4843 
.TRAP _TextSize $A88A 
.TRAP _MoveTo $A893 

.TRAP _DrawChar $A883 
.TRAP _CharWidth $A88D 
.TRAP = _NewPtr $A 100+39 

.IRAP — _DisposPtr $4000*31 


Xref SnakeText 


top EQU ø 
left EQU 2 
bottom EQU 4 
tblChar EQU ð 
tblTextSize EQU 2 
tblTop EQU 4 
tblLeft EQU 6 
tblBottom EQU 8 
tblRight EQU 1g 
tblRect EQU 4 
SnakeText : 

» on entry: 


; A0 points to string 
; Al points to rectangle to print string in Cleft edge 
should 
P be tight) 
, DØ = starting v 
MOVEM.L A2-A4/D3, -CSP) ;save some regs 
,Save inputs 
MOVE.L AQ,StringPtr(A5) 
MOVE.L Al,StringRectPtr(A5) 


MOVE DØ, vLocCA5) 
, init textSize to 12 point 

MOVE 812,-CSP) 

_TextSize 


,Set up a table (block of mem) to work with. Each char in 
j String will occupy 6 words in the table. One word for each 
of 
; the following: 
, char, curSizeOfChar, top, left, bottom, right 
;Each char has a rectangle defined by top, left, bottom and 
; right that encloses the char. This rect is used to erase the 
old 
; char before drawing the new Cand larger) char. 
MOVE.L StringPtr(A5), A0 
first byte of string is length byte. 
jwe need 12 bytes (6 words) for each char in string. 
CLR.L DØ 
MOVE.B (AØ), DØ; get length of string 
MOVE.L D0,D1 
ASL #2,DØ 
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ASL 83,01 MOVE vLoc(A5),-(SP) 


ADD D1,08 ;D0- 12*lengthCstring) -MoveTo 
;get a pointer to a block of DØ bytes of free RAM MOVE tblTextSizeCA4), -CSP) 
-NewPtr -TextSize 
MOVE.L A2,A2  ;copy BlockPtr (assume no err) MOVE tblCharCA42, -CSP) 
;initialize some stuff -DrawChar 
MOVE.L A2,BlockPtr(A5) CMPA.L A2,A4 have we reached FrontPtr? 
MOVE.L StringRectPtr(A52,A0 BEQ e6 
MOVE topCA2), TopValue(A5) ADDA 1" 12,A4 
MOVE lef tCA®),Lef tValueCA5) BRA e5 
MOVE bottomCA2),BottomValueCA5) 86 CMP 112,2(A3) ;is EndPtr size=12? 
MOVE.L StringPtr(A5),A3 BNE e7 
CLR D3 ADDA 1112, A3 ;inc EndPtr 
MOVE.B (A32*,D3 jget length of string e7 MOVE.L LastCharPtr(A52,A0 
SUBQ #1,D3 CMPA.L AØ,A2 jis FrontPtr at last char? 
;build the table BEQ e8 
; A2 = BlockPtr (pointer to current cher in table) ADDA 812,A2 ;inc FrontPtr 
; A3 = StringPtr (points to next char in string to work with) eg CMP 812,tblTextSizeCA2)  ;is last char's 
; D3 = length of string (loop control variable) ; size=12? 
82 MOVE.B (A32*,D0 ;get a char BNE 63 
MOVE DØ, tblCharCA2) ;save char in table 
CLR tblTextSizeCA2) ;textSize=8 to start MOVE.L BlockPtr(A5),A8 ;free the memory used 
MOVE TopValueCA5), tb] TopCA2) -DisposPtr 
MOVE Lef tValueCA5), tblLef t (A2) MOVEM.L CSP2*,A2-A4/D3 ;restore some regs 
MOVE BottomValue(A5), tb1BottomCA2) RTS 
CLR -(SP) ;Space for integer result StringPtr DS.L 1 
MOVE DØ, -CSP) ;push char StringRectPtr DS.L 1 
-CharWidth jget width of char LastCharPtr DS.L 1 
MOVE CSP +, DØ BlockPtr DS.L 1 
ADD Lef tValueCA5), DØ add char width TopValue DS 1 
; to previous BottomValue DS 1 
MOVE DØ, tb IRightCA2) ; LeftValue to get Lef tValue DS 1 
; RightValue vLoc DS 1 
MOVE DO, Lef tValueCA5) 
ADDA #12, A2 sinc table 
DitHiemlty 
Easy: computer moves randomly 
pointer Hard: computer thinks about moves 
DBRA D3, 62 
save ptr to last char in table 
812, A2 
MOVE.L A2,LastCharPtr(A5) 
OK 
MOVE.L BlockPtr(A52,42 jA2 = FrontPtr (Co J 
MOVE.L A2,A3 jA3 = EndPtr 
;,do the drawing ; Vic Tac Toe 
) : "LAM . 
; A4 = loop control variable ) ] March 1986 Mike Scanlin 
83 MOVE.L A2,A4 jStart with FrontPtr 
Include MacTraps.D 
svary the speed by putting an even factor of 12 (i.e. Include ToolEqu.D 
1,2,3,4,6) 
; in the line below. hine Eou — $100 
: 1 = slow (11 char lag) alse EQU 
; 2 = sorta slow (5 char lag) <-- set at 2 now rendSeed EQU -126 
: 3 = medium (3 char lag) Time EQU — $20C 
: 4 = fast (2 char lag) everyEvent EQU $FFFF 
) 
; * note, if you set it at 5, you'll regret it Chang system) re EQU — 250 
; 6 - really fast (1 cher lag) 3:4 Ls 
;Change the immediate data in the next line (84): eft EaU 2 
@4 ADDQ #2 tblTextSize(A4) — ;inc textSize(A4) | ¿codes for board: 
CMPA.L A3,A4 ;are we at EndPtr? empty EaU 8 
BEQ e5 Square EQU 1 
SUBA *12,A4 ;go to previous entry in table circle EU 2 
B5 PEA tblRect(A4) ‘erase old char ;external routines 
FraseRect i Xref SnakeText,GrowText 
MOVE tblLeft(A4),-(SP) ;draw new char 
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; internal routine and data used by GrowText 
Xref — CenterString,windowWidth 


PEA -4(A5) j; init everything 
-Init6raf 
-InitFonts 
-InitWindows 
-InitMenus 
PEA resume ;serious system error 
; resume procedure 
-InitDialogs 
-TEInit 
MOVE.L #everyEvent,D@ 
-FlushEvents 
-InitCursor 


,make Apple menu 
CLR. -(SP) ,Space for hndl result 
MOVE 81,-CSP) jmenu id 
PEA AppleMenuTitle 
-NewMenu 
,save handle, but leave it on the stack for -AppendMenu 
MOVE.L CSPD,AppleMenuHndl(A5) 
PEA AppleMenuAbout ;add 'about' 
-AppendMenu 
MOVE.L AppleMenuHndl(A52, -CSP) 
CLR -CSP) 


-InsertMenu 


make Game menu 


CLR.L -(SP) ,Space for hndl result 
MOVE 82,-(SP) jmenu id 

PEA GameMenuTitle 

-NewMenu 

MOVE.L (CSP2,GameMenuHndl(CA5) 

PEA GameMenuNew add New Game 
-AppendMenu 

MOVE.L GameMenuHndlCA5), -CSP) 

PEA GameMenuRev ;add Reverse Positions 
-AppendMenu 

MOVE.L GameMenuHndlCA5), -CSP) 

PEA GameMenuShow ;add Show Scores 
-AppendMenu 

MOVE.L GameMenuHndl(A5), -CSP) 

PEA GameMenuClear ;add Clear Scores 
-AppendMenu 

MOVE.L GemeMenuHndlCA5), -CSP) 

PEA GemeMenuLine ;add a line 
_AppendMenu 

MOVE.L GameMenuHndlCA5), -CSP) 

PEA GameMenuQuit — ;add Quit 
-AppendMenu 

MOVE.L GameMenuHndl(A5), -CSP) 

CLR - (SP) 

~Inser tMenu 


,disable the line and Reverse Positions 
MOVE.L GameMenuHndlCA5), -CSP) 


MOVE 85, -CSP) 
-DisableItem 
MOVE.L GameMenuHndlCA5), -CSP) 
MOVE 82,-(SP) 
-DisableItem 
make difficulty menu 
LR.L -(SP) ,Space for hndl result 
MOVE 83,-CSP) jmenu id 
PEA DiffMenuTitle 
-NewMenu 
MOVE.L CSP),Dif fMenuHnd1(A5) 
PEA Dif fMenuEasy ,8dd ‘easy’ 
-AppendMenu 
MOVE.L DiffMenuHndlCA5), -CSP) 
PEA DiffMenuHard ,add 'hard' 
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make Cheat menu 
CLR. 


-AppendMenu 

MOVE.L DiffMenuHndlCA5), -CSP) 

PEA GameMenuLine  ;add a line 
-AppendMenu 

MOVE.L DiffMenuHndlCA5), -CSP) 

PEA DiffMenuHelp ,add help 
-AppendMenu 

MOVE.L DiffMenuHndlCA5), -CSP) 

CLR -CSP) 

-InsertMenu 

MOVE.L DiffMenuHnd1CA5),-(CSP) ;disable the line 
MOVE 83,-CSP) 

-DisableItem 


-CSP) ,Space for hndl result 
MOVE 84,-(SP) jmenu id 
PEA CheatMenuTitle 
-NewMenu 
MOVE.L (CSP2,CheatMenuHnd1(A5) 
PEA CheatMenuYou add player cheat 
-AppendMenu 
MOVE.L CheatMenuHndlCA5), -CSP) 
PEA CheatMenuMe add computer cheat 
-AppendMenu 
MOVE.L CheatMenuHndl(A5), -CSP) 
PEA GameMenuLine  ;add a line 
-AppendMenu 
MOVE.L CheatMenuHndlCA52, -CSP) 
PEA CheatMenuHe Ip ,8add help 
-AppendMenu 
MOVE.L CheatMenuHndlCA5), -CSP) 
CLR -(SP) 
-Inser tMenu 
MOVE.L CheatMenuHndlCA5),-CSP) ;disable line 
MOVE 83,-CSP) 
-DisableItem 
-DrawMenuBar 


;init the dialogs' item list handles 
LEA 


about ItemsL ist, Ad 
LEA about! temsHnd1,A1 
MOVE.L A0,CADD 
LEA diffItensList,AQ 
LEA diffItemsHndl,A1 
MOVE.L A®,CA1) 


smake the "about" dialog, but don't show it (yet) 
CLR.L 


-(SP)  ;space for dialog ptr result 


CLR.L -(SP) ;jnil ptr CwStorage on heap) 
PEA aboutRect ;window coordinates 
PEA aboutTitle j title 

MOVE "false, -(SP) ;not visible 
MOVE 8dBoxProc, -CSP) ;Window type 
MOVE.L #-1,-C(SP) window in front 
MOVE "false,-(SP) jno closebox 
MOVE.L #1,-CSP) ,reference value 
PEA eboutItemsHndl 

-NewDialog 


MOVE.L (SP)+,aboutPointer(A5) ;save pointer 


smake the difficulty dialog, but don't show it (yet). 
,this dialog window is the same dialog used by the 'cheat' 
, Menu option 


LR.L -(SP) ;space for dialog ptr result 
CLR.L -(SP) ;nil ptr (wStorage on heap) 
PEA diffRect ,Window coordinates 
PEA diffTitle jtitle 
MOVE ®false,-C(SP) ,hot visible 
MOVE "dBoxProc, - CSP ) ;window type 
MOVE.L #-1,-C(SP) ,Window in front 
MOVE "false,-CSP) jno closebox 
MOVE.L *1,-CSP) ,reference value 
PEA diffItemsHndl 
-NewDialog 


MOVE.L (SP)*,diffPointer(A5) ;save pointer 
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;make score window, but don't show it Cyet) 
-(SP) ;space for window ptr result 


CLR.L -(SP) ;nil ptr CwStorage on heap) 
PEA sRect ;window coordinates 
PEA sTitle title 

MOVE *"false,-CSP) ;hot visible 
MOVE *inoGrowDocProc,-CSP) ;window type 
MOVE.L #-1,-(SP) ;window in front 
MOVE *false,-CSP) jno closebox 
MOVE.L #2,-CSP) jreference value 
-NewWindow 


MOVE.L (SP2*,sPointer(CA5) jsave pointer 
;make game window and show it 
-(SP) ;space for window ptr result 


CLR.L -(SP) ;nil ptr (wStorage on heap) 
PEA wRect ,window coordinates 
PEA wlitle jtitle 

MOVE ®true,-(SP) ,visible 
MOVE QnoGrowDocProc,-(SP) ;window type 
MOVE.L #-1,-CSP) ;window in front 
MOVE ®false,-CSP) jno closebox 
MOVE.L %3,-CSP) ;reference value 
-NewW indow 


j leave pointer on stack for .SetPort 
MOVE.L CSP), wPointer(CA5) 


-SetPort make game window the active window 
;set up to draw normal, 12 point Chicago text 

-PenNormal 

MOVE "g,-(SP) ;chicago 

_TextFont 

MOVE #9, -CSP) normal 

_TextFace 

MOVE #12,-CSP) ; 12 point 

-TextSize 


;get a ptr on the heap for a string of length maxNumStrSize. 
; the ptr is returned in AQ. This string is used later. 
; maxNumStrSize = length(max longint) -> 
; length('+2147483648') = 11 
MOVEQ  *11,D0 
-NewPtr 
MOVE.L A0,strPointer(A5) jsave string ptr 


;init randSeed with current time 
MOVE.L (452,48 ;get QuickDraw globals ptr 
MOVE.L Time,rendSeedCA2) 

;init some other stuff 


CLR MeWonCA5) 
CLR YouWonCA5) 
CLR CatsCA5) 
MOVE 8true,GameO0verCA5) jno current game 
MOVE ®false,ShowFlag(A5) score currently 
; hot shown 
MOVE S true, EasyFlag(A5) jstart off easy 
MOVE ®false,PlayerCheatsC(A5) ;no cheating 
; to begin with 

MOVE ®false, ComputerCheats(A5) 

GetEvent 
-SystemTask 

,wait for an event 
CLR -(SP) 
MOVE ÜeveryEvent, -CSP) 
PEA EventRecord 
-GetNextEvent 
MOVE CSP )+, DØ 
BEQ GetEvent 

;what event was it? 
MOVE What, D8 
CMP #12,D9 ;12 = MaxEvents 
BGE GetEvent 
ASL 8 1,D0 
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MOVE EventTableCD2),D9 
JMP EventTableCD0) 
EventTable 
DC GetEvent-EventTable ;null event #8 
DC mouseDown-EventTable ;mDown *1 
DC GetEvent-EventTable ¡mouse up #2 
DC keyDown-EventTable ;key down 83 
DC GetEvent-EventTable ;key up *4 
DC GetEvent-EventTable auto key 85 
DC update-EventTable ;update event #6 
DC GetEvent-EventTable X ;disk event #7 
DC GetEvent-EventTable ;activate #8 
DC GetEvent-EventTeble abort #9 
DC GetEvent-EventTable ;network #10 
DC GetEvent-EventTable ;1/0 driver #11 
;--------------- 
mouseDown 
P] 
CLR -(SP) ;Space for integer result 
MOVE.L Where,-CSP) 
PEA fndWindowCA5) 
-F indWindow j;where was mouse pressed? 
CLR.L DØ 
MOVE (SP)*,D0 
ASL 85 1,D0 
MOVE WindowTableCD2),D0 
JMP WindowTable(D@) 


ignore mouse 


presses inDsk, inSystemWindow, inDragRegion, 


; inGrowRegion and inGoAwayRegion. 


WindowTable 
DC GetEvent-WindowTable 
DC inMenuBr-W indowTable 
DC GetEvent-WindowTable 
DC inContentRegion-WindowTable 
DC GetEvent-WindowTable 
DC GetEvent-WindowTable 
DC GetEvent-WindowTable 
;------------ 
inMenuBr 
J 
CLR.L -(SP) ;space for longint result 
MOVE.L Where,-(SP) 
-MenuSelect which menu and which item? 
MOVE (SP)* ,menuChoiceIDCA5) 
MOVE CSP )+,menul temCA5 ) 
;jump to here for command keypress 
DecodeMenuBar 
CMP I 8] ,menuChoice IDCA5) 
BEQ inAppleMenu 
CMP I 82 menuChoiceIDCA5) 
BEQ inGameMenu 
CMP I ®3,menuChoiceIDCA5) 
BEQ inDif fMenu 
CMP I 84 menuChoiceIDCA5) 
BEQ inCheatMenu 
JMP GetEvent 
inApp leMenu 
CMP I #1,menultemCA5) jis it ‘about’ ? 
BNE ReturnFromMenu 


MOVE.L wPointer(A5),-CSP) junhilite current 


MOVE 


; front wndw 
"false,-(SP) 


-HiliteWindow 
jbring about wnds to the front, then show it and make it the 


; current port 


MOVE.L aboutPointer(CA52, -CSP) 
-BringToFront 
MOVE.L aboutPointer(A5), -CSP) 
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-ShowWindow 
MOVE.L aboutPointer(A5), -CSP) 


-SetPort 

,Set up some static text in the 'about' dialog 
OVE 88, -CSP) j typeface = outline 
-TextFace 


,center the text in the ‘about’ dialog. 
;Set up the 'windowWidth' variable used by CenterStr ing 
LEA 


aboutRect, Ad 
MOVE rightCA®), windowWidthCA5) get right 
MOVE lef tCA®), DØ ,get left 
SUB D,windowWidthCA5) jwidth= right - 
left 
sprint title of program 
LEA tttString, Ad 
JSR CenterString 
MOVE D£, -CSP) jh 
MOVE #28 ,-CSP) jV 
-MoveTo 
PEA tttString 
-DrewString 
sprint ‘written by...' 
MOVE 80,-CSP) ;type face = normal 
_TextFace 
LEA wbS tring, Ad 
LEA wbRect,A1 
MOVEQ  *t60,D0 
JSR SnakeText 
iprint date written 
LEA ww tring, Ad 
LEA wwRect,Al 
MOVEQ  *180,D0 
JSR SnakeText 


,outline the default response ("OK") in the standard way 
;hote: the outline is drawn before the actual button is drawn 
; (the button is drawn when -ModalDialog is called) 


LEA OKrect, Ad 

JSR DefaultOutline 
,wait for user response 

CLR.L -(GP)  ;nil ptr (no special filter 
routine) 

PEA itemHitCA5) 

-ModalDialog »wait for click or «ret» 
keypress 

TtemHit(A52,D0 

CMPI #1,DØ ;if they clicked 'OK' then leave 

BEQ @2 

PEA tyString ,else print ‘Thank You' 

PEA tyRect 

MOVE #114,-CSP) 

JSR GrowText 

MOVEQ #15,D1 ;let them look at it for a while 
84 MOVE 830000 , DØ 
e3 DBRA D£,es3 

DBRA D1,@4 
e2 MOVE.L aboutPointer(A52,-CSP) ,goodbye dialog 

-HideWindow 
ReturnFromMenu ,unhilite Apple menu 

-(SP) 
-HiLiteMenu 
JMP GetEvent 


tttString DC.B 11,'Tic Tac Toe’ 


wbStr ing DC.B — 24,'written by Mike’, 170,‘ Scanlin',@ 
wbRect DC 49,51,65, 208 
wwotring DC.B 35,'28 February 1986 York University’ 
wwRect DC 69, 39,85, 263 
tyString DC.B —9,'Thank you' 
tyRect DC 103, 110, 119, 179 
itemHit DS 1 
inGameMenu 
CMPI #1,menul temCA5) ,new game 
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BEQ NewGame 
CMP I 82,menuItem(A5) ;reverse positions 
BEQ ReversePositions 
CMPI 83, menuItem(A5) ;show/hide scores 
BEQ ShowScores 
CMPI 84, menul temCA5) ;clear scores 
BEQ ClearScores 
; 85 is a line 
CMPI $86, menuItemCA5) ;quit 
BEQ Finish 
JMP GetEvent 
NewGame 
f MOVEQ #8,DØ ¿Clear the old board 
LEA BoardCond, A 
e1 CLR (A2)* 
DBRA DO, @1 
MOVE "false,GameOver(A5) 


,enable Reverse Positions 
MOVE.L GameMenuHndl(A5), -CSP) 


MOVE 82 -C(SP) 

-EnableItem 

MOVEQ #2,DØ ;toss a coin to see who's first 
JSR RandomBounds 

CMP I #1,D1 ;on a 1, the player starts 


BEQ 62 jon a 2, the computer starts 
CMP I "false, EasyF lag(A5) 
BEQ e3 jif diff=easy, choose randomly 
MOVEQ #4,D1 ; else take middle Square 
BRA e 
,rendomly choose a square to start in 
e3 MOVEQ #9 Dé 
JSR RandomBounds 
SUBQ #1,D1 number from 0-8 
84 ASL 81,D1 ;01 = table offset 
LEA BoardCond, Ag 
MOVE "square, (A0,D1) 
e2 JSR DrawWindowContents 
JMP Re turnFromMenu 
DrawW indowContents 
MOVE.L wPointer(A5),-CSP) 
-SetPort 
,draw board 
MOVE 82,-(SP) 
MOVE 82,-(SP) 
-PenSize ,pen = 2x2 square 
MOVEQ #3,D3 ;number of lines to draw - 1 
LEA BoardL ines, A2 
e1 MOVE CA2)+,-CSP) 
MOVE (A2)+,-CSP) 
-MoveTo set pen location 
MOVE (A22*,-CSP) 
MOVE CA2)+,-CSP) 
-LineTo ,draw line 
DBRA D3,@1 
;draw pieces. Board is numbered like this: 
; 0 12 
; 3 4 5 
^ 6 7 8 
MOVEQ #8,D3 ;number of positions to check -1 
LEA BoardLocs, A2 
LEA BoardCond, A3 
84 MOVE.L A2,-CSP) ;,A2 points to rect 
-EreseRect ,erese old piece 
MOVE CA3)+, DØ 
BEQ e2 jif empty, do next position 


MOVE.L A2,-CSP) ,points to which square 
CMPI *square,D0 jis it a square? 
BNE e3 
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-FrameRect ;drew square 


BRA e2 
e3 -FremeOval ,drew circle 
e2 ADDA ?8,A2 point to next position in table 
DBRA D3,04 
MOVE 8$1,-CSP) 
MOVE 81,-CSP) 
-PenSize ;restore normal size pen 
RTS 


BoardCond DCB 9,0 ;Ü-empty, 1=sqaure, 2=circle 


BoardLocs DC 38,69 ,62,92 jsqeure 8 coordinates 
DC 38, 113,62, 145 si 
DC 38, 167,62, 199 2 
DC 83,60,115,92 33 
DC 83,113,115, 145 ;4 
DC 83, 167,115, 199 ;5 
DC 137,60, 169,92 ;6 
DC 137, 113, 169, 145 zT 
DC 137, 167, 169, 199 38 
BoardL ines DC 49,71,209,71 3Ch1,v1) Ch2,v2) 


DC 49, 125,209, 125 
DC 101, 19, 101, 179 
DC 155, 19, 155, 179 


ReversePositions 
“switch al] squares and circles 
MOVEQ %8,D8  ;number of positions to check -1 


LEA BoardCond, Ag 
e1 CMPI "empty, CAQ)*  ;if empty, 
; don't bother switching 
BEQ @4 


jcode for square=1, code for circle=2 
; 4 EOR 1 = 2; and 3 EOR 2 = 1 


EORI #3, -2CAB) ;Switch pieces 

e4 DBRA D2,e1 
JSR DrewWindowContents ;drew new board 
JMP ReturnFromMenu 

ShowScores 


; If the scores are not shown, then show them. If they are 
; currently shown, then hide them. In either case, toggle the 
; menu option from show to hide or visa versa. 


MOVE.L sPointerCA5),-CSP) ;for Show/Hide 


CMP I ®false,ShowFlag(A5) ;test flag 
BEQ @2 
HideW indow 
LEA ShowText, Ad 
BRA e1 
e2 -ShowW indow 
JSR DrawScoreW indow 
LEA HideText, Að 
e1 MOVE.L GameMenuHndlCA52, -CSP) 
MOVE 83,-CSP) ;item number to change 
MOVE.L A0,-CSP) ,pointer to item text 
-SetItem 


; flip the condition flag. 
; true EOR true = false; and true EOR false = true. 


EORI true, ShowF lagCA5) 

JMP ReturnFromMenu 
ShowF 18g DS 1 
ShowText DC.B — 10,'Show Score',0 
HideText DC.B — 10,'Hide Score',0 
ClearScores 

CLR MeWonCA5) 

CLR YouWonCA5) 

CLR CatsCA5) 

JSR DrawScoreW indow 
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€ Game Difficulty Mensiem 


E xo 


Cheating 


Anyone who is allowed to cheat is 
permitted to move on any square, 


even if someone is already there. 


sn] 


JMP ReturnFromMenu 
;------------- 
inDiffMenu 
CMPI #1, menul temCA5) 
BEQ EasyGame 
CMP I 82 menuItemCA5) 
BEQ HardGame 
; 83 is a line 
CMPI #4 menuItem(A5) 
BEQ DiffHelp 
JMP GetEvent 
EasyGame 


“if they selected a difficulty level, change the menu 
; appearance accordingly 
MOVE.L DiffMenuHndl(A5),-CSP) ;check easy 


MOVE 81,-CSP) 
MOVE 8true,-CSP) 
—CheckI tem 
MOVE.L Dif fMenuHnd1(A5),-CSP) ;uncheck hard 
MOVE 82 -(SP) 
MOVE "false,-CSP) 
-CheckItem 
MOVE 8true,EesyFlag(A5) ,difficultyszeasy 
JMP ReturnFromMenu 
HardGame 
MOVE.L Dif fMenuHnd1(A5),-CSP) ;uncheck easy 
MOVE 81,-CSP) 
MOVE ®false,-CSP) 
-CheckItem 
MOVE.L DiffMenuHndlCA52,-CSP) ;check hard 
MOVE 82 ,-(SP) 
MOVE 8true, -CSP) 
-CheckItem 
MOVE "?felse,EesyFlag(A5)  J;difficulty-hard 
JMP ReturnFromMenu 
;--------- 
DiffHelp 


MOVE.L wPointerCA52,-CSP) 


MOVE "false,-C(SP) 

-HiliteWindow 
jbring diff wndw to the front, show it end then make it the 
; current port 

MOVE.L diffPointer(A5),-CSP) 

Br ingToFront 
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junhilite current 
; front wndw 


MOVE.L dif fPointer(A5),-CSP) 


MOVE.L CheatMenuHndl(A5), -CSP) 


-ShowWindow MOVE #2,-(SP) 
MOVE.L diffPointer(A52,-CSP) MOVE ComputerCheats(A5),-(SP) 
-SetPort -CheckItem 
,Set up some static text JMP ReturnFromMenu 
MOVE 88,-(SP) ;text face = outline 
-TextFace jo DK RE 
LEA diffRect, Ad CheatHelp 
MOVE rightCAQ?,windowWidth(A5) ,get right Paani: 
MOVE lef tCAB), DØ MOVE.L wPointer(A5),-CSP) ,unhilite current 
SUB DØ, windowWidth(A5) ,Subtract left ; front wndw 
LEA diffString, Ag MOVE "false,-CSP) 
JSR CenterStr ing -HiliteWindow 
MOVE DØ, -(SP) jh ;bring cheat wndw (which is the diff wndw) it to the front, 
MOVE 828 ,-(SP) jV ; Show it and then make it the current port 
-MoveTo MOVE.L diffPointerCA5),-C(SP) 
PEA diffString -BringToFront 
-DrawString MOVE.L diffPointerCA5),-CSP) 
MOVE 80 ,-CSP) ,text face = normal -ShowWindow 
-TextFace MOVE.L diffPointer(A5),-(SP) 
MOVE 8#2ø,-(SP) -SetPort 
MOVE "70, -CSP) ,Set up some static text 
-MoveTo MOVE 88, -(SP) ; text face = outline 
PEA easyS tring _TextFace 
—DrawS tring LEA diffRect, Ad 
MOVE #20 ,-(SP) MOVE rightC(A@), windowWidth(A5) ,get right 
MOVE 895 -(SP) MOVE lef tCA®), DØ 
-MoveTo SUB D ,windowWidth(A5) ,Subtract left 
PEA hardStr ing LEA cheatString, Ad 
-DrawString JSR CenterString 
;outline the default response ("OK") in the standard way MOVE DO ,-CSP) ;h 
LEA OKrect, Ad MOVE 828,-(SP) jv 
JSR DefaultOutline -MoveTo 
,get user response PEA cheatStr ing 
CLR.L -(SP) ;nil ptr (no special filter -DrawStr ing 
routine) MOVE "0, -(SP) ; text face = normal 
PEA itemHitCA5) Tex tFace 
-ModalDialog ;wait for response ,draw some strings 
MOVE.L diffPointer(A5),-CSP) MOVE 830,-CSP) 
-HideWindow MOVE 865,-(SP) 
JMP ReturnFromMenu -MoveTo 
PEA inAnyCase 1 
diffString DC.B — 10,'Difficulty',0 -DrawStr ing 
easyStr ing DC.B 30,'Easy: computer moves randomly’ ,@ MOVE 830, -CSP) 
hardStr ing DC.B 34,'Hard: computer thinks about MOVE #09 -(SP) 
moves' ,@ -MoveTo 
PEA inAnyCase2 
AER pa er -DrawString 
inCheatMenu MOVE 830 ,-CSP) 
Q9 e se te ee eee MOVE 8115,-CSP) 
CMPI 81,menuItemCA5) -MoveTo 
BEQ PlayerCheat PEA inAnyCase3 
CMP I 32 menuItem(A5) -DrawString 
BEQ ComputerCheat ;Outline the default response ("OK") in the standard way 
;83 is a line LEA OKrect , Ad 
CMPI 84  menuItemCAb) JSR DefaultOutline 
BEQ CheatHe lp ,get user response 
JMP GetEvent CLR.L -(SP) ;nil ptr (no special filter 
routine) 
pe eee PEA itemHit(A5) 
PlayerCheat -ModalDialog . ,Wait for response 
Qj ceeceb n ede MOVE.L diffPointer(A52,-CSP) 
; toggle player cheat flag -HideWindow 
EORI *true,PlagerCheats(A5) JMP ReturnFromMenu 


; check/uncheck player cheats 
MOVE.L CheatMenuHnd1(CA5), -CSP) 


cheatStr ing DC.B — 8,'Cheating',0 


MOVE 

MOVE 
-CheckItem 
JMP 


toggle computer cheat flag 
EORI 


81,-CSP) 
PlayerCheats(A5), -CSP) 


inAngCase1 DC.B 
inAnyCase2 DC.B 
inAnyCase3 DC.B 


33,'Anyone who is allowed to cheat is' 
32, 'permitted to move on any squere, ',0 
33,'even if someone is already there." 
ReturnFromMenu 


;did they click in the game window? 
MOVE.L wPointer(A5),D8 
true, ComputerCheats(A5) CMP.L fndWindowCA5),D0 
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BNE e3 ;ho, ignore click 


CMPI ®true, GameOver (A5) ;is a game in 
; progress? 
BEQ e3 jno, ignore click 
player makes a move 
J 
e10 PEA Where jwhere did they click? 
-6lobalToLocal 
MOVEQ #8,D3 ;check all 9 squares 
LEA BoerdCond, A2 
LEA BoardLocs, A3 
e1 CLR -(SP) ,Space for boolean result 
MOVE.L Where,-CSP) 
MOVE.L A3,-CSP) ;Square coords 
-PtInRect ;is pt in this square? 
MOVE CSP )+, D8 
BNE @2 jyes, we have a valid click 
ADDA #2,A2 update BoardCond pointer 
ADDA #8, A3  ;updete BoardLocs pointer 
DBRA D3,@1 
BRA e3 snot in square -- ignore click 
;if player cheating is allowed, skip check 
@2 MPI S true, PlagerCheatsCAb) 
BEQ e 15 
MOVE €A2),08 ;check if taken 
BNE 83 ;if not empty then ignore click 
815 MOVE "circle, CA2) ;put the player there 
JSR DrewWindowContents 
JSR CheckWin ;check if plager hes won 
CMPI t true,D9 jif player didn't win, 
then 
BNE e7 ; computer will make a move 
ADDQ 8 1, YouWonCA5) 
BRA eit 


;computer makes a move 


;if the board is full, then cats game 
87 


LEA BoardCond, Ad 
MOVEQ #8,DØ 
e4 MOVE (AQ5*,D1 
BEQ e5 ;if we get one empty, then stop 
DBRA D, 84 
BRA e12 ,cats game -- all positions used 
@5 CMPI ®false,EasyF lag(A5) 
BNE 616 ;choose rendomly if not thinking 
JSR ComputerThinks 
CMPI 8 true, MadeMoveCA5) jif we didn't 
nove 
; when thinking 
BEQ @14 ; then choose 
; randomly 
816 LEA BoardCond, A2 
e6 MOVEQ — 9,00 
JSR RandomBounds 
SUBQ #1,D1 ;get a number in the range 2-8 
ASL #1,01 ;calc table offset 
CMPI 8 true, ComputerCheatsCAb) 
BNE e 18 sif not cheating, 
; make sure it's empty 
CMPI *square, CA2,D1) ;if cheating, make 
sure it's not a square. 
BEQ 06 jyes, it's a square. 
; try again. 
BRA e17 ;teke it Cit's a circle or 
empty) 
e18 CMPI empty, (A2,D1) 
BNE e6 ;this space is full. try again. 
817 MOVE *square,(A2,D1) ;put a square here. 
e14 JSR DrawWindowContents 
JSR CheckWin ;check if computer has won 
CMPI ®true,D8 
BNE e8 
ADDQ 8 1, MeWonCA5) 
BRA e11 
e8 MOVEQ  *8,D0 ;did comp make last 
; possible move? 
82 


e9 
left, 


e12 
811 


LEA 
MOVE 
BEQ 


DBRA 
ADDQ 
MOVE 


BoardCond,A®  ; look for empty positions 
(AQ0*,D1 


83 ; there's still space 
; game not over 

DB, e9 

$1, CatsCAb) cats game 

®true,GameOver(A5) 


;disable Reverse Positions 
MOVE.L GameMenuHnd1(A5),-CSP) 


MOVE 
-DisableItem 
JSR 

e3 JMP 

Computer Thinks 


#2,-(SP) 


DrawScoreWindow ;update score wndw 
GetEvent 


output A2 = points to BoardCond 


offset] 


; priority of checks: 


Di = 


2 * square to move to (2-8) [BoardCond table 


; Ist - check if computer can win in next move 
2nd - check if computer can block player win in next move 


; 4th - decide randomly 


3rd - check if middle square is taken 
d 
J 


; computer's piece 


= square, player = circle 


MOVE *false,MadeMove(CA5) 
;check 8 ways of winning 
MOVEQ 7,00 
LEA offsets,A1 
LEA BoardCond, Ad 
MOVEQ  "square,D1 
e1 MOVE CA1)+,A2 
MOVE CA1)+,A3 
MOVE CA1)+,A4 
JSR CheckPosition 
CMP I ® true, MadeMove(A5 ) 
BEQ @5 
DBRA DO, @1 
;check 8 ways of blocking 
MOVEQ  *7,D0 
LEA offsets,Al 
LEA BoardCond, Ad 
MOVEQ  8circle,D1 
e2 MOVE CA1)+,A2 
MOVE CA1)+,A3 
MOVE CA1)+,A4 
JSR CheckPosition 
CMPI ®true,MadeMove(A5) 
BEQ 85 
DBRA DB, 62 
;check if middle square is taken 
CMPI 8 true, ComputerCheats(A5) 
BNE e3 
CMPI *square, CA, A3) 
BEQ 85 
84 MOVE *Àsquare, CAD, A3) 
MOVE * true, MadeMoveCA5) 
BRA e5 
e3 CMPI empty, CAD, A3) 
BEQ 84 
@5 RTS 
offsets DC 9,6, 12,2,8, 14,4, 10,16 
DC 0,2,4,6,8, 10, 12, 14, 16 
DC 9,8, 16,4,8, 12 
MadeMove DS 1 
CheckPosition 


: used to see if any 2 of a CAØ,A2), b (A0,A3) and c CAO,A4) 


ere 


; occupied by the computer. If so, it tries to take the 3rd 
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(to 

; make a win). If the computer is allowed to cheat, it takes 
the 

; 3rd regardless of what's already there. On defense, this 

; routine is used to check if the computer can take the 3rd 

; Square to block a player win. The boolean variable MadeMove 
; reflects whether a move was made after this procedure has 
; finished. 


CMP CAO, A2),D1 jif a and b and (not c) 
BNE e2 
CMP CAO, A32,D1 
BNE 82 
CMPI Btrue,ComputerCheats(A5) 
BNE e3 
CMPI "square, CAG, A4) 
BEQ e2 
84 MOVE ®square, CA, A4) 
MOVE "true,MadeMove(A5) 
BRA e8 
e3 CMP I "empty, CAB, A4) 
BEQ 84 
62 CMP CAO, A2),D1 ; if a and c and (not b) 
BNE @5 
CMP (AB,A4),D1 
BNE e5 
CMPI *true, ComputerCheats(A5) 
BNE e6 
CMPI "squere, (A, A3) 
BEQ 85 
67 MOVE "square, (AD, A3) 
MOVE 8 true, MadeMove(A5) 
BRA e8 
e6 CMPI "empty, CA, A3) 
BEQ e7 
85 CMP CAO, A32,D1 jif b and c and (not a) 
BNE 68 
CMP CAG, A4), D1 
BNE ea 
CMPI 8Strue,ComputerCheats(A5) 
BNE e9 
CMPI "square, CAD, A2) 
BEQ eg 
e 10 MOVE "square, (A0, A2) 
MOVE Btrue,MadeMove(A5) 
BRA eg 
e9 CMPI "empty, (AB, A2) 
BEQ 010 
e8 RTS 
keyDown 
4 
BTST #cmdKey, Modifiers ,wes it a 
» command key? 
BEQ e1 jno, ignore keypress 
CLR.L -(SP ) ,Spece for longint result 
MOVE Message+2,-(SP) jkey that was 
, pressed 
—MenuKey 
MOVE CSP )+,menuChoiceID(A5) 
MOVE (SP +, menul tem(A5) 
JMP DecodeMenuBar 
e1 JMP GetEvent 
update 


, redraw the contents of the game window 
MOVE.L wPointer(A5),-CSP) 
-BeginUpdate 
JSR DrawW indowContents 

MOVE.L wPointer(A5),-CSP) 

-EndUpdate 

JMP GetEvent 
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| Finish 


4 

; release memory occupied windows and dialogs 
MOVE.L aboutPointer(A5),-C(SP) 
-DisposDialog 
MOVE.L diffPointer(CA52,-CSP) 
-DisposDialog 
MOVE.L sPointer(A5),-CSP) 
-DisposWindow 
MOVE.L wPointer(A52,-CSP) 
-DisposWindow 
RTS 


; if the "resume" button is clicked, return to finder. 
; this could be dangerous if the program seriously messed up 
; RAM in some way 

-ExitToShe11 


; check if someone has won Cif there are 3 in a row of any 
; non-blank) output: DØ = false if no win, true if won. 


LEA BoardCond, A 
MOVE CAO), DØ ;check row 1 
AND 2(A0),D0 
AND 4CA0),D0 
BNE Win 
e1 MOVE 6CA02,D0 ;Ccheck row 2 
AND 8CA0),D0 
AND 10CA0)5,D0 
BNE Win 
e2 MOVE 12CA0),D0 ;check row 3 
AND 14CA0),D0 
AND 16CA0), DØ 
BNE Win 
e3 MOVE CAO), DØ ;check column 1 
AND 6CA0),D0 
AND 12CA2),D0 
BNE Win 
84 MOVE 2CA0),D0 ;check column 2 
AND 8CA0),D0 
AND 14CA2)5,D0 
BNE Win 
85 MOVE 4CA0),D0 ,check column 3 
AND 1ØCA0), DØ 
AND 16CA0), DØ 
BNE Win 
@6 MOVE CAO), DØ ;check neg slope diagonal 
AND 8CA0),D0 
AND 16CA25,D0 
BNE Win 
e7 MOVE 4(40),D0 ;check pos slope diagonal 
AND 8CA0),D0 
AND 12(A0),D0 
jat this point, if DØ=Ø then (DO-false and leave) else set 
; D@=true 
BEQ NoWin 
Win MOVE ®true, DO 
NoWin RTS 
RandomBounds 
; input DØ = max number to return 
; Output Di = (random mod DØ) + | Calways positive) 
MOVE D ,-CSP) jsave DØ 
CLR -(SP) ,Space for integer result 
-Random 
MOVE (SP)+,D1 ,get random num 
ANDI #$7FFF,D1 result = pos 15-bit num 
MOVE (SP )+, DØ ,restore DØ 
DIVS D9,D1 
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SWAP D1 ;remainder (MOD) is in low word MOVE.L wPointer(CA52,-CSP) 


ADDQ #1,D1 -SetPort 
RTS RTS 
IR xeu cn a scoreRect DC 1,50,60, 75 
DrawScoreWindow 
2 
MOVE.L sPointer(A5),-CSP) ;make score GetRandomString 
;wndw current port aa aaa ace ME 
-SetPort ; get a random number, then fall through to NumToString to 
erase old scores ; covert to string 
LEA scoreRect, Ad CLR -CSP) ;space for integer result 
MOVE.L A0,-CSP) Random 
-EreseRect CLR.L DØ ;set up DØ as longint for 
;do computer's score -NumToString 
MOVE 8$15,-(SP) ;set pen location MOVE CSP )+, DØ 
MOVE 815,-CSP) MOVE.L strPointer(A52,A0 ;addr of string 
-MoveTo june aera 
PEA 'Me:' ;draw a string NumToS tring 
_DrawStr ing jeep eee ae RU 
MOVE.L strPointer(A52,A0 ;convert score to ; convert a number to a string 
; String ; input DO = number 
CLR.L DØ P Að = addr of string to put number in 
MOVE MeWon(CA52,D0 MOVE 80 -(SP) ;routine selector 
JSR NumToStr ing Pack? ;Pack7 = _NumToString 
CLR -(SP) ;right justify the number ;A@ now points to string with the number Cunchanged from 
MOVE.L strPointerCA5),-CSP) ; before) 
-StringWidth RTS 
MOVEQ #75,D8 
SUB CSP )+, DØ a aca ater 
MOVE D, -CSP) jh CenterString: 
MOVE #15, -(SP) M (oem ce aun deis ue. 
-MoveTo ; input A8 = addr of string 
MOVE.L strPointer(A5),-CSP) ;draw the score i windowWidth = width of window to center in 
-DrewString P (should be set before calling this routine) 
;do player's score CLR -(SP) ;space for integer result 
MOVE #15,-CSP) MOVE.L A®,-CSP) 
MOVE 130, -(SP) -StringWidth 
-MoveTo MOVE windowWidthCA52,D0 
PEA "You: ' SUB (SP )+, DO 
DrawString ; DØ = offset to start printing 
MOVE.L strPointerCAS), Ad ASR #1, DØ ;CwindowWidth - StrWidth) div 2 
CLR.L DØ RTS 
MOVE YouWonCA5),DØ 
JSR NumToString windowWidth: DS 1 
CLR -(SP) 
MOVE.L strPointerCA5),-CSP) mu ci MC ER LEE 
-StringWidth DefaultOutline 
MOVEQ #75,DØ jgencewepeuME UE 
SUB (SP )+, DØ ;make a thick oval around a button to show that it is the 
MOVE DØ, -CSP) jh default 
MOVE 830, -CSP) jV ; (the one that will be selected if RETURN or ENTER is 
-MoveTo ; pressed). 
MOVE.L strPointer(CA52, -CSP) ; input: AØ = pointer to the rect to draw around 
_DrawS tring LEA workRect(A5),A1 ,;make a copy of 
;do-cats games ; the rect 
MOVE 815,-CSP) MOVE.L CAQ)+, CA1)+ 
MOVE #45 ,-CSP) MOVE.L (AØ), CA1) 
_MoveTo PEA penState(A5)  ;save penState 
PEA 'Cets:' -GetPenState 
-DrewString MOVE 83,-CSP) ;make a fat pen 
MOVE.L strPointerCA52,A0 MOVE 83,-CSP) 
CLR.L DØ -PenSize 
MOVE Cats(Ad), D8 PEA workRect(A5) ;make rect bigger 
JSR NumToStr ing MOVE #-4 -(SP) 
CLR -(SP) MOVE 8-4 -(SP) 
MOVE.L strPointer(A5),-CSP) -InsetRect 
-StringWidth PEA workRect(A5) ;make the fat border 
MOVEQ #75,D0 MOVE #16,-CSP) 
SUB (SP )+, DØ MOVE #16,-CSP) 
MOVE DO, -CSP) jh -FrameRoundRect 
MOVE 145, -(SP) Vv PEA penState(A5) restore penState 
-MoveTo -SetPenState 
MOVE.L strPointer(A52,-CSP) RTS 
-DrewString 
;set game window to be the active port workRect DS 4 
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penState DS 


wlitle 
wRect 
wPointer 


sTitle 
sRect 
sPointer 


aboutTitle 
aboutRect 
aboutPointer 


11,'Tic Tac Toe’ 
68, 128,260, 382 
1 


5, 'Score' 
60,401,112,491 
1 


1, a a 
85, 107,256, 397 
1 


CheatMenuHndl DS.L 
CheatMenuTitle DC.B 
CheatMenuYou DC.B 
CheatMenuMe 

CheatMenuHelp DC.B 


menuChoice ID 
menul tem 
strPointer 
fndWindow 

EasyF lag 
PleyerCheats 
ComputerCheats DS 
MeWon DS 
YouWon DS 
Cats 

GameOver 


1 
6, 'Cheats',0 


23, ‘Player Allowed to Cheat' 


DC.B — 25,'Computer Allowed to Cheat' 


25, 'What',39,'s all this 


Cheating? ' 

DS 1 
DS 1 
DS.L 1 
OS.L 1 
DS 1 
DS 1 
1 

1 

1 

DS 1 
DS 1 


about I temsHndl DC.L 
aboutI temsList DC 


—s 


3 eT of items in list - 1 
DC L 


jbutton #1 
OKrect DC s, 213, 165,278 
DC.B ;ctrlItemsbutCtr] 
d 2, i button. resource 'ICON' 128 'MIKEFACE' 
DC 145, 18, 165, 130 DC.L $003FF800,$03FFFF80, $0FFFFFEO, $ IFFFFFFO 
DC.B 4 jctrlItemtbutCtr] DC.L $1FFFFFFøØ,$3E3FF878, $3803C038, $300000 1C 
DC.B — 11,'That',39, 's nice', DC.L $70FC3F 1C, $7303C00C, $74624C3C, $T0F25F3C 
xs i ee ;Mike icon DC.L $7C652C3C,$3C05A23C, $3A08905C, $39FØCF98 
DC.B — 168 ° :iconItentitemDisable DC.L $18004010,$08077010,$04070820, $04000020 
DC.B 2 DC.L $649 15026, $0406FA20, $04 176020, $02 1DFF20 
DC 128 | | DC.L $02190240,$011FFE40,$0 1080480, $0087F880 
de 1 m ;Fishtree icon DC.L $00400100,$00200200, $00 180C00, $000 7F 000 
DC.B — 160 ` -iconItem+itenDisable 
DCB 2 resource 'ICON' 129 'FISHTREE' 
DC 129 DC.L $00670000,$0008E1C0, $0302 1830, $040 10388 
e DC.L $0F008COB,$18788008,$ 10848008, $ 1302 1F04 
vM de e T DC.L $14012084,$08 194044, $0864 C48, $288422 10 
diffPointer DSL 1^ 7^" DC.L $090C2110,$0610 10E0, $00 100800, $00 100800 
diff ItemsHnd] DC.L 1 DC.L $00200400,$0021C400,$00222400,$00200400 
diffItemsList DC Ø ;number of items in list - 1 
DCL Ø ;button #1 
DC 145, 213, 165,278 
DC.B ;etr1I tem+butCtr] 
DC.B 2. "OK! 
EventRecord 
What DC Ü 
Message DCL Ø 
When DCL Ø [ 
Where DCL Ø 
Modif iers DC Ü 
LINK TicTacToe 
AppleMenuHnd] DS.L 1 FILE SnakeText 
AppleMenuTitle DC.B 1,28 GrowText 
App leMenuAbout DC.B 17, ‘About Tic Tac Toe' 


/RESOURCES 
GameMenuHnd] DS.L 1 TicTacToe_rsrc 
GameMenuTitle DC.B 4, ‘Game’ n. 
GameMenuNew DC.B 10, ‘New Game /N' ,e 
GameMenuRev DC.B 19, "Reverse Positions/R' 
GemeMenuShow DC.B 12, ‘Show Score/S',@ 
GameMenuClear DC.B 12, ‘Clear Scores‘ Ø 
GameMenuLine DC.B 1, m 
GameMenuQuit DC.B 6, "Quit/Q',0 


DiffMenuHndl DS.L 1 

DiffMenuTitle DC.B X 10, ‘Difficulty’, Ü 

DiffMenuEasy DC.B 6, "Easy! ', 18,0 

DiffMenuHard DC.B 4, ‘Hard’ E, 

DiffMenuHelp DC.B 25, ‘What’ ,39,'s with these 
levels?’ 
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C Workshop 


Programming for HFS Compatibility 


Mike Schuster 
Consulair Corp. 


C 


Foreword 


The Apple “Hierarchical 
File System” is a major advance 
in Macintosh technology. From 
the programmer's standpoint, 
HFS is an an extension to the 
current file manager. Many calls 
are the same, some calls have 
been extended, and there are 
some new HFS -specific 
extensions. 

Internally, however, HFS is 
a brand-new file system. The 
Apple developers have done a 
wonderful job of making it 
compatible. HFS must be a part 
of any serious programmer's 
understanding. 

I had planned for Mike to 
do two articles, to cover for me 
during the peak of start-up 
activity on our VAX AppleTalk 
contract and preparations for the 
DECUS Symposium and 
DEXPO show. His first article, showing how to do “pop-up” 
menus, was very good. 

However, this month's article is so important and so full 
of useful information, that I have asked him to follow up with 
a second article, this time covering HFS internals. Next 
month, Mike will cover the “on-disk structures” of HFS and 
details of HFS internal data structures. Now ... onward. 


Bob Denny 
November, 1985 


Programming for HFS Compatibility 


Apple's new Hierarchical File System (HFS), shipped 
with Apple's Hard Disk HD20 and used by Finder 5.0, 
provides a much more effective mechanism for managing large 
volumes than the original Macintosh File System (MFS), 
represented by Finder 4.1 and below. In MES, all of the files 
on a volume are indexed in a single directory organized as an 
unsorted, linear list of files names. 

While adequate for small volumes, this structure proved 
inefficient for handling larger Storage devices containing 
hundreds of files. When a call is made to open a file, an 
exhaustive, linear search must be performed to find that file's 
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Status April Chart. May Chart 


Fig. 1 HFS Directories Explained 


7 oN LAIN 
Document Folder Application Folder 
—— N 
[4] | AAA 
ZIN "E = "a 


MacPaint MacWrite MacDraw 


N 
: yj folders become directories 
01: HFS File Structure 


directory entry. As the number of files on the volume 
increases, these searches become relatively time consuming. 

The Hierarchical File System abandons this flat, unsorted 
approach and instead employs a hierarchical file directory, 
known as the File Catalog. The file catalog organizes and 
maintains the user's perceived desktop hierarchy of folders 
(directories) which contain other folders and files. The catalog 
is organized as a B" Tree for quick searching and enumeration 
of files and folders in the hierarchy. 

In addition to providing fast access to a large number of 
files, the catalog provides the Finder with the information it 
needs to render the desktop, without the substantial overhead of 
recreating in memory a tree describing the relationships 
between folders and files. 

MFS performs volume space management and file extent 
mapping using a Allocation Block Map (ABM). In this 
Scheme, space on the volume is allocated in equal sized units 
called allocation blocks. The ABM contains an entry for each 
allocation block on the volume. An entry is zero if the 
corresponding allocation block is free, and otherwise equals the 
index of the next allocation block in the associated file. 

To guarantee fast space management and file access, MFS 
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keeps the entire ABM for each mounted volume in memory. 
Thus, the ABM must be kept to a reasonable size, 
constraining the size of an allocation block. For larger 
volumes, this requirement results in severe storage 
fragmentation and wastage (in which the size of an allocation 
block often exceeds the median file size), and forces the 
partitioning of a storage device into several smaller, 
independent volumes, only a few of which are mountable at 
any one time. 

The Hierarchical File System abandons the ABM scheme 
and employs instead a volume space map (VSM) and a 
hierarchical file block allocation structure. The VSM is used 
only for space management and contains one bit per allocation 
block on the volume, requiring an order of magnitude less 
space than a corresponding ABM. A bit in the VSM is one if 
the corresponding allocation block is in use, and otherwise is 
zero. File mapping is based on a B*-Tree structure which 
provides efficient sequential and random file mapping. 

Apple designed the Hierarchical File System to be 
upwards compatible with the MFS. Apple was quite 
successful. Most applications written for MFS work correctly 
under HFS. The Hierarchical File System supports the 
existing MFS disk volumes and allows all existing MFS calls 
to access HFS volumes. 


File Catalogs and Pathnames 


A file catalog organizes the folders and files (both called 
nodes ) on a volume into a hierarchical tree structure. Folders 
are equivalent to directories in traditional file systems; they 
contain other folders and files. Figure 1 shows an example of 
HFS file and folder layout. 

The node at the base of the catalog, named StartUp, is the 
root folder. By convention, its name is also the name of the 
volume. Internal nodes are folders that contain other folders 
and files. Folders and the nodes they contain are connected by 
branches in the figure. 

A folder at the top of a branch is the parent of the folder 
or file offspring at the bottom. The offspring of StartUp are 
the folders System Folder, Document Folder, and Application 
Folder. No two offspring of the same parent may have the 
same name. 

Leaf nodes do not have branches beneath them; they are 
either empty folders or files. The files Products, Logo, and 
MacPaint are all leaves. 

Every folder in the catalog has a unique directory ID. On 
an HFS volume, the root folder always has a directory ID of 2; 
other folders have positive integers as directory ID's. In the 
figure the directory ID of the node System Folder is 10. Since 
offspring have unique names, every node in the catalog can be 
uniquely identified by its name and the directory ID of its 
parent, which is called the node's parent ID. The node 
specification pair {parent ID, node name} in fact constitutes 
the "key" used to search through the B*—Tree for a particular 
node. It corresponds to the quickest way for HFS to find a file 
or folder. 

Another way to identify a node in a catalog is by a 
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pathname. A pathname is a concatenation of node names, 
each separated by a colon. The node corresponding to the 
name on the left of each colon must be the parent of the node 
corresponding to the name on the right. A pathname 
identifying the file Status with parent ID 14 is: 


StartUp:Document Folder:Sales Folder:Status 


A pathname that starts at the root, such as the one above, 
is called a full pathname. It provides a second way of uniquely 
identifying a node. 


Another way of identifying a node is by a partial 
pathname, which describes a path to a node starting from any 
folder in the catalog. Partial pathnames start with a colon, 
except in the special case where the partial pathname contains 
only one name. When using partial pathnames, the directory 
ID of the folder from which the pathname begins must also be 
specified. 

A partial pathname identifying the file Status with parent 
ID 12, starting from Document Folder (3) is: 


‘Sales Folder:Sales Charts:Status 


This pathname begins at Document Folder and moves 
down the tree to Status. It is also possible to move up the 
tree by using two or more consecutive colons. 

A pathname identifying the file Status with parent ID 14, 
starting from Document Folder is: 


:Sales Folder:Sales Charts::Status 


Since character strings are limited by the file system to at 
most 255 characters in length, it may not be possible to 
identify every node in a catalog with a full pathname. 

To access a file deep within a catalog of a large volume, 
an application must construct a full pathname to reach some 
intermediate folder along the path to the desired file and obtain 
that folder's directory ID. Then it must use that directory as 
the starting point for a partial pathname to reach the file or 
another folder further along the path. 


Working Directories and File System 
Compatibility 


The Hierarchical File System provides yet another way of 
identifying a particular node in a catalog. An application may 
specify a particular folder as a working directory and then later 
use this working directory as a shorthand notation to identify 
nodes relative to that directory. When the file system creates a 
working directory, it stores the folder's directory ID as well as 
a reference to the volume on which the folder resides into a 
working directory control block (WDCB). The file system 
then returns a unique working directory reference number 
(WDRefNum) which the application uses on subsequent calls 


€ The Complete MacTutor, Vol. 2 


to the file system to refer to this folder. Each working 
directory control block also contains an identifier that allows 
discrimination between working directories set up by different 
callers. Typically, the identifier equals the application's 
creator bytes. This convention allows unneeded WDCB to be 
easily identified when transfering between applications. 

Working directories and their reference numbers are the 
keys to upward compatibility with MFS. Like volume 
reference numbers, working directory references numbers are 
negative integers, but the set of WDRefNums are always 
distinct from the set of VRefNums. Hence, a WDRefNum 
may be substituted for a VRefNum in any file system call 
without ambiguity. When a WDRefNum is used in place of a 
VRefNum, the file system looks up the volume reference 
number and directory ID from the associated working directory 
control block. 

The HFS Standard File Package uses this scheme to 
allow the user to select from files in different directories 
without changing Standard File's external interface. The only 
difference is that a WDRefNum is returned instead of a 
VRefNum in the SFReply.vRefNum field. If the application 
simply passes this value to the PBOpen routine, the desired 
file will be opened. Existing applications under MFS that use 
Standard File in this manner will properly run without 
modification under HFS. 

Applications that take the SFReply.vRefNum, convert it 
to a volume name and then concatenate the SFReply.fName, 
will not function correctly under HFS — the user can only 
open files in the root directory of the volume (in fact, such 
applications do not even run correctly under MFS; there could 
be two mounted volumes with the same name). Consult the 
Macintosh Technical Note #49: "HFS Compatibility Issues" 
for further information. 


File Manager Calls 


The Hierarchical File System supports all existing MFS 
calls to both MFS and HFS volumes and provides a set of 
additional calls that operate on the catalog hierarchy of HFS 
volumes directly. HFS also provides a set of extensions to 
some of the MFS calls that provide additional functionality 
and information. The table in figure 2 at the end of this article 
lists each call alphabetically, its trap word, and the structure of 
the call's I/O parameter block. 

HFS calls that are extensions of existing MFS routines 
use the same trap word as the corresponding MFS call, except 
that bit 9 of the trap word is set. These calls are listed in the 
table on the same line as their corresponding MFS call. The 
entirely new HFS calls share a common trap word A260 
C HFSDispatch); the individual routines are identified by a call 
identifier word placed in register DO. Like all other calls, 
_HFSDispatch returns an I/O result code in DO. 

All of the HFS calls take a directory ID as an input 
parameter, specified in the new I/O parameter block field 
ioDirID. This directory ID is used to refer to the folder itself 
or, in conjunction with a partial pathname from that folder, to 
other nodes in the catalog. The specification of a directory ID 
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in the ioDirID field overrides the directory ID specified by a 
WDRefNum in the ioVRefNum field. If this is undesireable, 
set ioDirID to zero. If a VRefNum is passed in ioVRefNum, 
a ioDirID of zero will default to the root directory ID. 

The basic functions of the HFS calls are summarized 
below. (see the Apple User Education publication "The File 
Manager," 10/8/85 or later, for more information): 


PBAllocContig is identical to PBAllocate, but forces the 
allocation of a single contiguous set of allocation blocks. 


PBCatMove moves files or folders from one folder to 
another on the same volume. The source is specified by 
ioVRefNum, ioDirID and ioFileName. The destination is 
specified by ioNewDirID and ioNewName. 


PBCloseWD closes a working directory allocated by 
PBOpenWD. 


PBHCreate is identical to PBCreate, but accepts a directory 
ID in ioDirID. 


PBHDelete is identical to PBDelete, but accepts a directory 
ID in ioDirID. PBDelete and PBHDelete may be used to 
delete folders, but the folder must be empty before it can be 
deleted. 


PBDirCreate is identical to PBCreate, except that it creates 
a new folder instead of a file. It accepts a directory ID in 
ioDirID. 


PBGetCatInfo returns a superset of the information returned 
by PBGetFInfo in an enlarged parameter block. PBGetCatInfo 
works on folders as well as files. It accepts a directory ID in 
ioDirID and a value in ioFDirIndex which specifies how the 
node is to be identified. Information may be returned for a 
specified node, or for the nth node in a folder. 


PBGetFCBInfo returns information about an open file 
given its path reference number in ioRefNum, or for the nth 
open file, where n may be limited to count only files on a 
given volume. 


PBHGetFInfo is identical to PBGetFInfo, but accepts a 
directory ID in ioDirID. 


PBHGetVInfo returns a superset of the information returned 
by PBGetVInfo in an enlarged parameter block. 


PBHGetVol returns the default volume and default directory. 
PBHGetWDInfo returns information contained in a working 
directory given its WDRefNum, or for the nth working 
directory, where n may be limited to count only working 
directories having a specified descrimination identifier. 


PBHSetVInfo allows modification of information associated 
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with a volume. 


PBHOpen is identical to PBOpen, but accepts a directory ID 
in ioDirID. 


PBHOpenREF is identical to PBOpenRF, but accepts a 
directory ID in ioDirID. 


PBHOpenWD opens a working directory. PBHOpenWD 
returns a WDRefNum in ioVRefNum. 


PBHRename is identical to PBRename but accepts a 
directory ID in ioDirID. PBHRename cannot change the 
directory a file is in. PBRename and PBHRename may be 
used to rename folders. 


PBHRstFLock is identical to PBRstFLock, but accepts a 
directory ID in ioDirID. 


PBSetCatInfo allows modification of a superset of the 
information modified by PBSetFInfo. It works on folders as 
well as files. 


PBHSetFInfo is identical to PBSetFInfo, but accepts a 
directory ID in ioDirID. 


PBHSetFLock is identical to PBSetFLock, but accepts a 
directory ID in ioDirID. 


PBHSetF Vers is identical to PBSetFVers, but accepts a 
directory ID in ioDirID. 


PBHSetVol sets the default volume as well as the default 
directory. 
Example C Code 


The following routines are offered as examples of HFS 
usage. I chose them both to illustrate some of the new calls 
as well as to provide useful ingredients for inclusion in your 
own toolbox. 


Enumerating a Volume's Files 


The first example shows how to enumerate all of the files 
on all mounted volumes. The function enumerate takes a 
single argument fileproc; a pointer to a function. Fileproc is 
an “action routine" that you supply, and is called once for each 
file found on each volume. It should be declared as: 


int fileproc(vrefnum, vp, fp) 
int16 vrefnum; 
HVolumeParam *vp; 
HFilelnfoParam *fp; 


Each time fileproc is called, it is passed three arguments; 


a VRefNum or WDRefNum indicating which volume and 
directory contains the file, a pointer to the volume's 
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information parameter block, and a pointer to the file's 
information parameter block. Enumerate supports the both 
MFS and HFS volumes. It is also designed to work on MFS 
only machines.Enumerate begins by searching for mounted 
volumes using a loop: 


for (vp.ioVollndex = 1; IPBHGetVInfo(&vp, 0); 
vp.ioVollndex--4 ) 


The ioVolIndex field indexes the volumes sequentially, 
without gaps, so it can be used as a way of finding mounted 
volumes. The loop terminates when the error nsvErr (no such 
volume) is returned. The HFS call PBHGetVInfo can be made 
to a system supporting MFS calls only, since bit 9 in the trap 
word is ignored by MFS. 

After volume information has been obtained, enumerate 
decides if the volume is HFS or MFS. This is done via the 
test: 
if (FCBLen == -1 || vp.ioVSigWord == mfsSigWord) 


Enumerate first checks the global word FCBLen (address 
Ox3f6). If this word is -1, the file system supports MFS calls 
only. Otherwise its value equals the length of the file control 
block (FCB) and indicates that both MFS and HFS calls are 
supported by the file system. 

If HFS calls are supported, then the volume's file system 
signature word ioVSigWord is checked. Its value is 
mfsSigWord (0xd2d7) for MFS volumes and hfsSigWord 
(0x5456) for HFS volumes. In this test, FCBLen is checked 
first, since the ioVSigWord field is not defined by MFS. 

The files on an MFS volume are found using a loop: 


for (dp.ioFDirlndex = 1; IPBGetFInfo(&dp, 0); 
dp.ioFDirlndex++) 


The ioFDirIndex field indexes the files sequentially, 
without gaps, so it can be used as a way of finding all files. 
The loop terminates when the error nsfErr (no such file) is 
returned. Fileproc is invoked once for each file. 

The files on an HFS volume are found using a breath 
first search of the volume's file catalog. The algorithm 
enumerates the offspring of each folder in the catalog, starting 
at the root, and maintains a queue of those folders that have 
been encountered in the search, but whose offspring have not 
yet been enumerated. The field ioVDirCnt, in the volume's 
information parameter block, specifies the total number of 
folders in the volume's catalog. Its value is an upper bound 
on the size of the queue. 

Before the offspring of a folder are enumerated, a working 
directory for the folder is created so that a WDRefNum can be 
passed to fileproc as its vrefnum argument. The 
descrimination identifier of the working directory is set to 
'ENUM. Then the offspring of the folder are enumerated 
using a loop: 
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for (dp.ioFDirlndex = 1, dp.ioDrDirlD = dir; 
IPBGetCatInfo(&dp, 0); dp.ioFDirlndex++, dp.ioDrDirlD = dir) 


The ioFDirIndex field indexes the offspring sequentially, 
without gaps. The ioDrDirID field in the PBGetCatInfo call 
is both an input and an output parameter. On input, it equals 
the folder's directory ID (maintained by the variable dir); on 
Output, it equals the file number or the directory ID of the 
offspring. The ioDirFlg flag (0x10) in the ioFlAttrib field 
discriminates the offspring as a folder or a file. If the 
offspring is a file, fileproc is called, otherwise the folder is 
placed on the queue. The folder's working directory is closed 
after the last of its offspring is found. After completing the 
loop and closing the working directory, enumerate then 
handles the next folder in the queue, if any. 


enumerate(fileproc) 
mt (*fileproc)(); 


HVolumeParam vp; 
DirInfoParam dp; 
WOParam wp; 
Str255 vname; 
Str255 dname; 
int32 **dirs; 
int32 *dirp; 
int32 dir; 

int ok; 


/* initialize params */ 


vp. ioNamePtr = &vname; 
dp.ioNamePtr = &dname; 
wp.ioNamePtr = 91; 


wp.ioWDProcID = 'ENUM'; 

/* enumerate each volume */ 

for (OPERARE = 1; !PBHGetVInfo(&vp, Ø); vp. ioVolIndext+) 
dp. ioVRefNum = vp. ioVRefNum; 


/* if MFS volume, enumerate each file x/ 
if CFCBLen == -1 || vp.ioVSigWord == mf sSigWord) 
for Cdp.ioFDirIndex = 1; 
(*f i leproc)Cdp. ioVRefNum, &vp, &dp); 


/* if HFS volume, allocate space for directory queue */ 


else if (dirs = (int32 **) NewHandleCvp.ioVDirCnt * sizeofCint325)) 
( 


/* place root into directory queue */ 
HLock(dirs); 

dirp = *dirs; 

*dirp** = rootDirID; 


/* enumerate directory queue */ 
i: (dirp > *dirs) 


dir = *--dirp; 
wp. ioVRefNum = dp. ioVRefNum; 
wp. 1OWDDir ID = dir; 


/* open working directory */ 
if vail aa 0)) 


/* enumerate files in directory */ 
for Cdp.ioFDirIndex = 1, dp. ioDrDirID = dir; 
IPBGetCatInfoC&dp, 0); dp. ioFDirIndex**, 
dp.ioDrDirID = dir) 
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IPBGetFInfoC(&dp, Ø); dp. ioFDirIndex++) 


/* if offspring is a directory, place on 
queue */ 
if Cdp.ioFlAttrib & ioDirFlg) 
*dirp** = dp.ioDrDirID; 


/* if offspring is a file, call argument 
function */ 

else 

(*f i leproc)(Cwp. ioVRefNum, &vp, &dp); 


/* all done with working directory */ 
eee ø); 


) 
DisposHandleCdirs); 


Constructing a Full Pathname 


The second example shows how to determine the full 
pathname of a working directory identified by its WDRefNum. 
The function pathname takes a pointer to the resulting string, 
a WDRefNum, and an integer specifying the maximum length 
of the string. In a manner similar to the previous example, 
pathname works for both MFS and HFS volumes, as well as 
on MFS only machines. 

If the argument WDRefNum refers to a MFS volume, or 
to the root directory of a HFS volume, pathname simply 
returns the volume's name. Pathname accomplishes this by 
checking the volume's signature word and comparing the 
argument WDRefNum to the volume's VRefNum. 

If the argument WDRefNum refers to a working directory, 
then its directory ID is found using the PBGetWDInfo call. 
Pathname uses this directory ID as a starting point for a walk 
up the volume's file catalog. At each step toward the root, the 
PBGetCatInfo call is made to find the folder's name, which is 
appended to the front of the accumulated pathname 
via the functions strtac and stmtac (the reversed 
versions of strcat and strncat). As a reference, the 
definition of strtac follows pathname. 

Notice that the  ioFDirIndex field of 
PBGetCatInfo's parameter block is set to -1. This 
value forces PBGetCatInfo to return information 
about the folder identified by the directory ID in ioDirID, and 
to ignore the name (if any) in ioNamePtr. In this way, 
PBGetCatInfo treats ioNamePtr as an output only field and 
uses it only to return the folder's name. 


char *pathname(pname, wdrefnum, n) 
char *pname; 
int16 wdrefnum; 
int16 n; 


HVolumeParam vp; 
WDParam wp; 
DirlnfoParam dp; 
Str255 dname; 


/* initialize params */ 
pname[0] = ^0"; 
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n--; 
vp.ioNamePtr = &dname; 
vp.ioVRefNum = wdrefnum; 


The final example shows a sample usage of the functions 
enumerate and pathname. It prints the full pathname of each 


file on all mounted volumes. 
vp.ioVollndex = 0; 
wp.ioNamePtr = Ol; fileproc(wdrefnum, vp, fp) 
wp.ioVRefNum = wdrefnum; int16 wdrefnum; 
wp.ioWDindex = 0; HVolumeParam “vp; 


wp.ioWDProcID = Ol; 
dp.ioNamePtr = &dname; 
dp.ioFDirlndex = -1; 


DirlnfoParam “fp; 


char name[256]; 


/* get volume information */ 


pathname(name, wdrefnum, sizeof name); 
if ((IPBHGetVInfo(&vp, 0)) 


ptocstr(fp-»ioNamePtr); 
/* if MFS or HFS root, return volume name */ printf("%s:%s\n", name, fp->ioNamePtr); 
if (FCBLen == -1 || vp.ioVSigWord == mfsSigWord || ctopstr(fp->ioNamePtr); 
vp.ioVRefNum == wdrefnum) 
strncat(pname, ptocstr(vp.ioNamePtr), n); 
main() 


/* get working directory information */ 

"n if ((PBGetWDInfo(&wp, O)) enumerate(&fileproc); 
/* traverse path from working directory to root */ 
dp.ioVRefNum = wp.ioWDVRefNum; 


iig Consulair C Version 
iia ParlD = wp.ioWDDirlD; Double-Clickable Application 

l* get next node information */ r Put the above routines together into a complete program. */ 
: : : /* This example and glue routines are specific to */ 

dp.ioDrDirlD = dp.ioDrParID;  Provid imilar front end f C syst 7 

if (PBGetCatInfo(&dp, 0)) rovide a similar Tront end tor your U system. 
break; include "stdio.h" 

/* concatenate node name to result */ Nincuoo ctm 

strntac(strtac(pname, ":"), extern StringPtr ctopstr(); 


ptocstr(dp.ioNamePtr), n - 1); 


n -= strien(dp.ioNamePtr) + 1; extern char “ptocstr(); 


extern char *strcat(); 


} ; : 
while (dp.ioDrDirlD != rootDirlD); ner Nobb NM 
/* remove last colon */ extern char “strntac(); 


extern char *strtac(); 


pnamej[strlen(pname) - 1] = ^0"; extern OSErr pbCall0(); 


^ pname, #define PBCloseWD(pb, a) 


pbCall0(pb, a, OxA260, 2) 
#define PBOpenWD(pb, a) 
pbCall0(pb, a, OxA260, 1) 
#define PBGetWDInfo(pb, a) 
pbCall0(pb, a, OxA260, 7) 


char “strtac(s1, s2) 
register char *s1, “s2; 


register char *result = s1; 


register int n = strlen(s2); #define PBHGetVInfo(pb, a) 


while (*s1--4) pbCall0(pb, a, 0xA207) 
E #define PBGetCatlnfo(pb, a) 

while (--s1 >= result) pbCall0(pb, a, OXA260, 9) 

*(s1 +n) ="s1; #define PBGetFinfo(pb, a) 
S1++; pbCall0(pb, a, OXAO0C) 
while (*s2) 

*s1+4+ = “S2++; tasm 
return result; pbcalld: 
} tst.b — di 

ord oB e 
Using the Examples e1 leo 62, a0 
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Fig. 2 New Trap Calls for HFS 


move .w d2, (ad) 
move. ] d£ , a0 
nove.»  d3,d0 MES Calls Parameter 
e2 ids PBAllocate A010  IOParam 
endasm PBClose A001  lOParam 
* PBCreate A008  FileParam 
/* place enumerate code here */ PBDelete A009  FileParam 
P a * PBEject A017 Param 
place pathname code here */ PBFlushFile A045  lOParam 
: PBFlushVol A013 Param 
/* place fileproc code here */ 
PBGetEOF A011  lOParam 
PBGetFInfo AOOC  FileParam 
PBGetFPos A018  l|OParam 
PBGetVInfo A007 VolumeParam 
PBGetVol A014 Param 
PBMountVol AOOF  Param 
PBOffLine A035 Param 
PBOpen A000  lOParam 
PBOpenRF AOOA  lOParam 
PBRead A002  lOParam 
PBRename AOOB  lOParam 
PBRstFLock A042  FileParam 
PBSetEOF A012  lOParam 
PBSetFInfo AOOD  FileParam 
PBSetFLock A041  FileParam 
SetFPos A044 |OParam 
PBSetFVers A043  lOParam 
PBSetVol 015 Param 
PBUnmountVol AOOE Param 
PBWrite 003  lOParam 


fs.h file for lair 


"define int8 char 

"define int16 short 

"define int32 long 

typedef char *Ptr; 

typedef Ptr *Handle; 

typedef int16 C*ProcPtr)O; 
int16 */ 

typedef ProcPtr *ProcHandle; 
*/ 


/* 8-bit integer */ 

/* 16-bit integer */ 
/* 32-bit integer */ 
/* pointer */ 

/* handle */ 

/* pointer to proc ret 


/* handle to proc ret int16 


"define String(size) struct (unsigned char length; 

cher text[size];) 
typedef String(255) Str255; /* max length pascal str */ 
typedef Str255 *StringPtr; /* ptr to max length p str 
ey 


typedef StringPtr *StringHandle; 
str*/ 

typedef int16 OSErr; 

*/ 


/* handle max length p 
/* operating sys err code 


typedef Mer OS Type; f e type code d T 
r mrtr r e men 
define FüBLen Secink 16 =) axarey ^x Rts £2 MRFS Se lengih 
of FCB */ 

"define mfsSigWord @xd2d7  /* MFS volume signature */ 

#def ine hfsSigWord 0x4244 /* HFS volume signature */ 

8define rootDirID 2 /* HFS root vol dir id */ 
“define ioDirFlg x10 /* catalog node dir flag */ 


typedef ( truct 


OSType fdType; 
OSType fdCreator; 
int16 fdF lags; 

int16 fdLocation[2]; 
int16 fdFldr; 

) FInfo, *FInfoPtr; 


/* file's type */ 

/* file's creator */ 
/* flags */ 

/* file's location */ 
/* file's window */ 
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HES Calls 


PBAllocContig 
PBCatMove 


PBCloseWD 
PBHCreate 
PBHDelete 
PBDirCreate 


PBGetCatinfo 


PBGetFCBlnfo 
PBHGetFinfo 


PBHGetVInfo 
PBHGetVol 
PBGetWDiInfo 
PBHSetVInfo 


PBHOpen 
PBHOpenRF 
PBOpenWD 


PBHRename 
PBHRstFLock 
PBSetCatlnfo 


PBHSetFInfo 
PBHSetFLock 


PBHSetFVers 
PBHSetVol 


typedef poe 


QElemPtr qLink; 
int16 qType; 

int16 ioTrep; 

Ptr ioCmdAddr; 
ProcPtr ioCompletion; 
OSErr ioResult; 
StringPtr ioNamePtr; 
int 16 ioVRefNum; 
int16 ioRefNum; 

int8 ioVersNum; 

int8 ioPermssn; 

Ptr ioMisc; 

Ptr ioBuffer; 

int32 ioReqCount; 
int32 ioActCount; 
int 16 ioPosMode; 
int32 ioPosOffset; 


) IOPerem, *10ParanPtr; 


typedef ( truct 


QElemPtr qLink; 
int16 qType; 

int16 ioTrap; 

Ptr ioCmdAddr; 
ProcPtr ioCompletion; 
OSErr ioResult; 
StringPtr ioNamePtr; 
int16 ioVRefNun; 
int16 ioFRefNum; 
int8 ioFVersNum; 
int8 filler; 

int16 ioFDirIndex; 
int8 ioFlAttrib; 
int8 ioFlVersNum; 
FInfo ioFlFndrInfo; 
int32 ioFlNum; 


A210 HlOParam 

A260,5 CMoveParam 

A260,2 WDParam 

A208 HFileParam 

A209 HFileParam 

A260,6 HFileParam . 

A260,9 HFilelnfo/DirlnfoParam 
A260,8 FCBParam 

A20C HFileParam 


A207 HVolumeParam 
A214 DParam 
A260?7 . WDParam 
A260,11  HVolumeParam 
A200 HiOParam 
A20A HIOParam 
A260, 1 WDParam 
A20B HlOParam 
A242 HFileParam 
A260,10 HFileinfo/DirinfoParam 
A20D HFileParam 
A241 HFileParam 
A243 HlOParam 
A215 WDParam 


next queue entry */ 

queue entry type */ 

routine trap */ 

routine address */ 
completion routine */ 

result code */ 

name */ 

reference number */ 

path reference number */ 
version number */ 

read/write permission */ 
miscellaneous */ 

data buffer */ 

requested number of bytes */ 
actual number of bytes */ 
position mode and newline */ 
positioning offset */ 


next queue entry */ 
queue entry type */ 
routine trap */ 
routine address */ 
completion routine */ 
result code */ 

name */ 

reference number */ 
path reference number */ 
version number */ 
unused */ 

Sequence number */ 
attributes */ 

version number */ 
finder information */ 
file number */ 
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int16 ioF1StBlk; 
*/ 

int32 ioFlLgLen; 
fork */ 

int32 ioF 1PyLen; 
x/ 

int16 ioFlRStBlk; 
*/ 

int32 ioFIRLgLen; 
sf | 

int32 ioFlRPyLen; 
*/ 


int32 ioF1CrDat; 
int32 ioF 1MdDat; 


/* 
/* 
/* 
/* 
/* 
/* 


/* 
/* 


Ist alloc block of data fork 
logical end-file of data 
phys end-file of data fork 
ist alloc block of res fork 
logical end-file of res fork 
phys end-of-file of res fork 


creation date */ 
modification date */ 


) FileParam, *FileParamPtr; 


typedef did 


QElemPtr qLink; 
int16 qType; 
int16 ioTrap; 
Ptr ioCmdAddr; 
ProcPtr ioCompletion; 
OSErr ioResult; 
StringPtr ioNemePtr; 
int16 ioVRefNum; 
int32 filler2; 
int16 ioVolIndex; 
int32 ioVCrDate; 
int32 ioVLsBkUp; 
int16 ioVAtrb; 
int16 ioVNmF 1s; 

5] 
int16 ioVDirSt; 
int16 ioVBlLn; 

*/ 
int16 ioVNmA1BIks; 
int32 ioVAIB1kSiz; 
int32 ioVClpSiz; 
int16 ioAIBISt; 

*/ 
int32 ioVNxtFNum; 
int16 ioVFrBlk; 

ei] 


/* 
/* 
/* 
/* 


/* 


next queue entry */ 

queue entry type */ 

routine trep */ 

routine address */ 
completion routine */ 

result code */ 

neme */ 

reference number */ 

unused */ 

volume index */ 

creation time end date */ 
lest backup time and date */ 
attributes */ 

number of files in directory 


first block of directory */ 
length of direct. in blocks 


no. of allocation blocks */ 
size of allocation block */ 
no. of bytes to allocate */ 
Ist allocation block in map 


next unused file number */ 
no. of unused alloc blocks 


) VolumeParem, *VolumeParamPtr ; 


typedef als 


QElemPtr qLink; 
int16 qType; 
int16 ioTrep; 
Ptr ioCmdAddr ; 
ProcPtr ioCompletion; 
OSErr ioResult; 
StringPtr ioNemePtr; 
int16 ioVRefNum; 
int16 ioRefNum; 
int16 filler; 
int32 ioFCBIndx; 
int32 ioFCBFINm; 
int16 ioFCBF lags; 
int16 ioFCBStBIk; 
file */ 
int32 ioFCBEOF; 
int32 ioFCBPLen; 
int32 ioFCBCrPs; 


/* 
/* 
/* 


/* 


next queue entry */ 
queue entry type */ 
routine trep */ 
routine address */ 
completion routine */ 


/* result code */ 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


/* 
/* 
/* 


name */ 

reference number */ 

path reference number */ 
unused */ 

fcb index for .getfcbinfo */ 
file number */ 

flegs */ 

first allocation block of 


logical end-of-file */ 
physical end-of-file */ 
mark */ 


int16 ioFCBVRefNum; /* volume reference number */ 


int32 ioFCBClpSiz; 
int32 ioFCBParID; 


/* 
/* 


) FCBPeram, *FCBParemPtr; 


typedef struct 
QElemPtr qLink; 


int16 qType; 
int16 ioTrep; 
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/* 
/* 
/* 


file clump size */ 
perent directory id */ 


next queue entry */ 
queue entry type */ 
routine trep */ 


Ptr ioCmdAddr; /* routine address */ 
ProcPtr ioCompletion;  /* completion routine */ 
OSErr ioResult; /* result code */ 

StringPtr ioNamePtr; ^ /* name */ 

int16 ioVRefNum; /* reference number */ 

int16 ioRefNum; /* path reference number */ 
int8 ioVersNum; /* version number */ 

int8 ioPermssn; /* reed/write permission */ 
Ptr ioMisc; /* miscellaneous */ 

Ptr ioBuffer; /* data buffer */ 

int32 ioReqCount; /* requested number of bytes */ 
int32 ioActCount; /* actual number of bytes */ 
int32 filler; /* unused */ 

int32 ioDirID; /* directory id */ 


) HIOPerem, *HIOParemPtr; 


typedef iuh 


QElemPtr qLink; /* next queue entry */ 
int16 qType; /* queue entry type */ 
int16 ioTrap; /* routine trap */ 

Ptr ioCmdAddr; /* routine address */ 
ProcPtr ioCompletion;  /* completion routine */ 
OSErr ioResult; /* result code */ 

StringPtr ioNemePtr; ^ /* name */ 

int16 ioVRefNum; /* reference number */ 
int16 ioFRefNum; /* path reference number */ 
int16 filler2; /* unused */ 

int16 ioFDirIndex; /* sequence number of file */ 
int8 ioFlAttrib; /* ettributes */ 

int8 filler3; /* version number */ 


FInfo ioFlFndrInfo; /* finder information */ 
int32 ioDirID; /* directory id */ 


int16 ioF IStBik; /* ist alloc block of data fork 
:/ 

int32 ioFlLgLen; /* logical end-file of data 
fork */ 

int32 ioFlPyLen; /* phys end-file of data fork 
x 

int16 ioF IRStBIk; /* 1st alloca block of res 
fork */ 

int32 ioFlRLgLen; /* logical end-f ile of res fork 
di 

int32 ioF 1RPyLen; /* phys end-of-file of res fork 
*/ 

int32 ioF1CrDat; /* creation time and date */ 

int32 ioF 1MdDat; /* modification time and date 
zi 


) HFileParam, *HFileParamPtr; 


typedef struct 


QElemPtr qLink; /* next queue entry */ 

int16 qType; /* queue entry type */ 

int16 ioTrep; /* routine trep */ 

Ptr ioCmdAddr ; /* routine address */ 

ProcPtr ioCompletion;  /* completion routine */ 

OSErr ioResult; /* result code */ 

StringPtr ioNemePtr; ^ /* name */ 

int16 ioVRefNum; /* reference number */ 

int32 filler4; /* unused */ 

int16 ioVolIndex; /* volume index */ 

int32 ioVCrDate; /* creation time and date */ 

int32 ioVLsMod; /* modification time and date 
*/ 

int16 ioVAtrb; /* attributes */ 

int16 ioVNmF Is; /* number of files in directory 
*} 

int16 ioVBitMap; /* first block of vol bitmap 
a 

int16 ioVAllocPtr; /* vol space allocation ptr */ 

int16 ioVNmAIBlks; /* no. of allocation blocks */ 

int32 ioVAIB1kSiz; /* size of allocation block */ 

int32 ioVClpSiz; /* default clump size */ 

int16 ioATBISt; /* first block in block map */ 

int32 ioVNxtFNum; /* next free node id */ 


O The Complete MacTutor, Vol. 2 


int 16 
x/ 
int16 
int16 
int16 
int16 
int32 
int 16 
int32 
int32 
int32 
int32 


) HVolumeParam, *HVolumePa 


ioVFrBIk; 


ioVSigWord; 
ioVDrvinfo; 
ioVDRefNum; 
ioVFSID; 
1oVBkUp; 
ToVSeqNun; 
ioVWrCnt; 
ioVFilCnt; 
ioVDirCnt; 
ioVFndrInfot81; 


typedef struct 


QE lemP 
int16 
int16 


tr qLink; 
qType; 
ioTrap; 


Ptr ioCmdAddr; 


ProcPtr ioComp let ion; 


OSErr 


ioResult; 


StringPtr ioNameP tr ; 


int 16 
int 16 
int 16 
int 16 


ioVRef Num; 
ioFRefNum; 
filler; 
ioFDir Index: 


int8 ioFlAttrib; 


int8 f 
FInfo 
int32 
int16 


*/ 
int32 
fork */ 
int32 
*/ 


int 16 
*/ 

int32 
x/ 


int32 
int32 
int32 


int32 
FInfo 
int32 
int32 


*/ 


) HFileInfoParam. *HF ileIn 


lypedef struct 
( 
QElenP 


iller2; 
ioFlFndrInfo; 
ioF Num; 

ioF 1StBIk; 


ioF ILgLen; 

ioF 1PyLen; 

ToF IRStBIk; 
ioF IRLgLen; 
ioF 1RPyLen; 
ioF 1CrDat; 

ioF IMdDat; 

ioF 1BkDat; 

10F 1XFndr Info; 


ioF 1Par ID; 
i0F1C1 pSiz; 


tr qLink; 


int16 qType; 


int 16 


ioTrep; 


Ptr ioCmdAddr; 


ProcPtr ioCompletion; 


/* 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


/* 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


/* 


— 
* 


/* 
/* 
/* 
/* 
/* 


no. of unused alloca biks 


volume signature */ 

drive number */ 

driver reference number */ 
file system identifier */ 
last backup time and date */ 
seq no. in backup set */ 
volume write count */ 

number of files on volume */ 
no. of directories on vol */ 
finder information */ 


remPtr; 


next queue entry */ 
queue entry type */ 
routine trep */ 

routine address */ 
completion routine */ 
result code */ 

name */ 

reference number */ 

file reference number */ 
unused */ 

file directory index */ 
attributes */ 

unused */ 

finder information */ 
file number */ 

first alloc blk of data fork 


logical end-of-file data 
phys end-of-file data fork 
Ist alloca blk of res fork 
logical end-file of res fork 
phys end-file of res fork */ 
creation time and date */ 
modification time and date 
last backup time and date */ 
additional finder info */ 


parent directory id */ 
file's clump size */ 


foParamPtr ; 


next queue entry */ 
queue entry type */ 
routine trap */ 
routine address */ 
completion routine */ 
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*/ 


*/ 


OSErr ioResult; /* result code */ 

StringPtr ioNamePtr ; /* name */ 

int16 ioVRefNum; /* reference number */ 

int16 ioFRef Nun; /* file reference number */ 
int16 filler; /* unused */ 

int16 ioFDirIndex; /* file directory index */ 

int8 ioFlAttrib; /* attributes */ 

int8 filler2; /* unused */ 

int 16 ioDrUsrWds [8]; /* directory's user info */ 
int32 ioDrDirID; /* directory id */ 

int16 ioDrNmF 1s; /* number of files in directory 
int16 filler3(9]; /* unused */ 

int32 ioDrCrDat; /* creation time and date */ 
int32 ioDrMdDat; /* modification time and date 
int32 ioDrBkDat; /* last backup time and date */ 
int16 ioDrFndrInfo[8]; /* finder information */ 

int32 ioDrPer ID; /* parent id */ 


int32 filler4; /* unused */ 


typedef struct 


) DirInfoParan, *DirInfoParamPtr; 

QElemPtr qLink; /* next queue entry */ 
int16 qType; /* queue entry type */ 
int16 ioTrep; /* routine trap */ 

Ptr ioCmdAddr; /* routine address */ 
ProcPtr ioConp let ion; /* completion routine */ 
OSErr ioResult; /* result code */ 
StringPtr ioNemePtr; /* name */ 

int16 ioVRefNum; /* reference number */ 
int32 filler; /* unused */ 

StringPtr ioNewNane; /* new name */ 

int32 f iller2; /* unused */ 

int32 joNewD ir ID; /* new directory id */ 
int32 f iller3[2]; /* unused */ 

int32 ioDirID; /* directory id */ 


) CMoveParan, " CHoveParamPtr; 


typedef struct 


*/ 


QElemPtr qLink; /* next queue entry */ 

int16 qType; /* queue entry type */ 

int16 ioTrap; /* routine trap */ 

Ptr ioCndAddr ; /* routine address */ 
ProcPtr ioCompletion; /* completion routine */ 
OSErr ioResult; /* result code */ 

StringPtr ioNameP tr; /* name */ 

int16 ioVRefNum; /* reference number */ 

int16 filler; /* unused */ 

int 16 ioWD Index; /* working directory index */ 
int32 ioWOProcID; /* working directory's id */ 


int 16 ioWDVRefNun; 
int16 filler2(7); 
int32 ioWDDir ID; 


/* working dir vol ref no. */ 
/* unused */ 
/* working directory's dir id 


Gel 


) WDParam, *WDParanPtr; 


A 
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HD 20 Hierarchial File System Compatibility Chart 


This chart summarizes which programs are currently working under Finder 5.0 and the HD 20. HFS refers to the program running 
normally under the new Finder 5.0 on the Apple hard disk. LASER refers to the program printing correctly on the Apple Laserwniter 
printer. Note that Finder 5.1 is already planned for release this month! Root refers to files having to be at the root level of 

hierarchy, like the present MFS system and thus indicates that they don't work with folders. 


Application 


Finder 5.0 
Pagemaker 1.0 
Font/DA Mover 2.5 
MacDraw 1.9 
MacPaint 1.5 
MacPascal 1.0 
MacProject 1.0 
MacTerminal 2.0B3 
MacWirite 4.5 
MDS 1.0 
PaintMover 0.03 
QuickFile 0.5 
Switcher 4.4 

Manx C 1.0 
Omnis-3 3.10 
Statview 1.0 

Copy II Mac 42 
MacLion 3.1 
Consulair C 2.0 
ExperLisp 1.03 
ExperLogo 1.1 
OPSS 1.03 
Smoothtalker 1.0 
Filemaker 1.0 
Great Plains 3.03A 
ConcertWare 1.0 
VideoWorks 
Ensemble 1.0 
Smartcom II 2.1B 
MacDraft 1.1 
MacNosy 1.0 
Thinktank 512 1.1 
Jazz 

TK!Solver 1.0 
Slideshow Magician 
MacPublisher 1.31 
Chart 1.0 

Excel 1.0 

File 1.0 

Multiplan 1.02 
Word 1.05 

Fortran 77 2.0 
Dollars & Sense 1.2 
Helix 1.13 

Crunch 1.0 
OverVUE 2.0b 
MacOneWrite 2.0 
Paint Cutter 1.0 
Electric Checkbook 
Click Art 1.0 
Filevison 1.0 
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HFS? 


yes 
yes 
yes 
yes 
yes 
no 
yes 
yes 
yes 
no 
yes 
yes 
no 
no 
no 
yes 
no 
no 
no 
no 
yes 
no 
no 
yes 
no 
yes 
yes 
no 
no 
yes 
yes 
yes 
yes 
yes 
no 
no 
yes 
yes 
yes 
yes 
yes 
no 
no 
no 
no 
no 
no 
yes 
no 
yes 
no 


LASER? 


yes 
yes 


NOTES 


get Finder 5.1 with Mac Plus or HD 20 rev B start-up. 

help files and aldus prep must be in same folder. Ver. 1.1 current. 
somewhat buggy under HFS on 800K floppy drives. Use Open cmd. 
some printing problems with font and size combinations. 

Very compatible, solid, highly recommended. 

copy protection scheme renders it useless on HD 20. Watch for 2.0 
works well with HFS. 

vastly improved in the new 2.0 version due out in January. 

earlier versions of HFS had strange bugs with MacWrite. 

requires all files in the root. Being revised for HFS compatibility. 

Bill Atkinson utility for MacPaint stuff. Works ok. 

Rolodex substitute. Data file must be in same folder as program. 

Save set applications must be in same folder. Don't run Finder on it. 
Very Unix like. But requires all files be in the root. Look for Update. 
Default file names in dialog boxes can't be found. 

Uses SANE; very accurate, not protected, highly recommended. 

bit copy won't work with 800K drives or HD 20 due to new hardware. 
Difficult to use, not HFS compatible. 

same problem as MDS Edit. Cannot open files in the editor. 

copy protection makes it incompatible. 

features bunny graphics; works okay, annoying copy protection. 

copy protection makes it incompatible. 

Bombs with ID=10 on launch and corrupts system file! 

works great, very fast, not protected, reasonably priced. Best Buy! 
accounting software package does not launch. 

place instruments at same level as appl. Some laser printing problems. 
works ok with HFS. 

cannot find datafiles. No laser printing. Difficult to use. 

Impressive terminal package, but fails to use standard file package. 
Fixes some printing problems over Draw. But Files are put to root. 
very useful disassembler. User interface could be improved. 

Bombs with Macsbug but works with switcher & HFS. Laser problems. 
slow with large documents. 

cannot find it's help files on HD 20. But a great program, works fine. 
ver. 1.2 cannot find files under HFS. Series laser printing bugs. 
cannot recognize files it creates under HFS. 

use Excel instead. Laser printing problems. Works under HFS though. 
developed in parallel with HFS. Works great. Very fast. Best Buy! 
some minor cosmetic bugs. Index files restricted to certain folders. 
Get Excel. Works better with laser than File!? No problems with HFS. 
works better with laser. Fine with HFS. Place Glossary in appl. folder. 
Absoft/Microsoft product can't find files for passes 2,3 and 4! 
Selecting "File" from menu bar bombs nicely with an ID=25. 
intermittant problems under HFS. 

problems with cut and paste. 

poor printing options. Copy protection makes it incompatible. 

can't find data files on launch; must be in root. 

no problems with HFS. Great paint document tool. 

ver. 1.1 can't find it's parameter files. Does not recognize HD 20. 
Paint effects tool DA for MacPaint works fine with HFS. 

Does not use standard file. Watch for 512K upgrade. Printing bombs. 


Sel 


(on “=” = N 
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C Workshop 


Laser Print DA for Postscript 


Using a POSTSCRIPT Server on AppleTalk 


Most Macintosh applications generate printed pages by 
issuing a sequence of QuickDraw calls which are intercepted 
and translated into printer dependent commands by Apple's 
Printing Manager. This technique has the advantage that an 
application never needs to know what kind of printer the user 
has connected to the Macintosh. It also allows the application 
to write to the screen and the printer with a single device 
independent routine. On the other hand, it does not provide the 
application access to the extensive page description 
capabilities nor the wide range of printer resolutions available 
in modern electronic printing systems, such as those embodied 
in Adobe Systems' POSTSCRIPT page description language, 
Apples LaserWriter™ laser printer and Linotype's 
Linotronic™ 100 typesetter. This is because Quickdraw is 
much more limited in it's abilities than is POSTSCRIPT, and 
hence only a fraction of the capability of a POSTSCRIPT 
machine is needed to interpret a set of Quickdraw commands. 


$ 
SEC 
xe 


Fig. 1 
Postscript 
Output 
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Mike Schuster 


Software Engineer 
MacTutor Contributing Editor 


laser print 


In this article, I show how your application may 
overcome QuickDraw and the Printing Manager limitations by 
communicating directly with a POSTSCRIPT server on an 
AppleTalk network. In addition, I describe the 
implementation of Laser Print, a desk accessory that 
concurrently spools POSTSCRIPT programs you create with 
MacWrite, Edit or Just Text, and sends them to the Apple 
LaserWriter or other POSTSCRIPT compatibile printer. You 
can use this printing desk accessory to explore programming 
your LaserWriter directly, using an example postscript file in 
this article. In future issues of MacTutor, we will expand on 
postscript programming techniques with a regular postscript 
column and this desk accessory will be invaluable as a way of 
sending your programs over Appletalk to the Laser Writer. The 
Laser Print DA is written in MegaMax C. 


Deep Background 
by 
The Editor 


[When a Macintosh Application prints, the text and 
graphics that it writes to a quickdraw port to display on the 
Screen are sent to a special quickdraw port used by the printing 
manager. You print text and graphics by drawing into this port 
with Quickdraw, just as if you were drawing on 
the screen. The Printing Manager changes the 
pointers to the low-level drawing routines so 
that Quickdraw calls drive the printer rather than 
the screen. In this way, MacWrite can display a 
what- you- see- is- what- you- get screen version 
of your document with one set of routines and it 
can go to 
either the 
Screen or the 
printer thanks 
to the clever 
Printing 
Manager. The 
whole point of the Print Manager and associated 
device drivers is to convert Macintosh Quickdraw 
text and graphic descriptions into page bit maps 
that can be printed. This design works very well 
with the Imagewriter. 

Now comes the LaserWriter, after the 
Macintosh. This device is very different from 
anything Apple has ever produced and one can 
only wonder who was the mastermind behind it. 
It is so much more powerful than the Mac itself, 
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one has to wonder if it was an outside design. In some respects 
the LaserWriter is a high powered Macintosh. Substitute 
POSTSCRIPT for Quickdraw. Substitute 0.5 Meg of ROM 
for 64K ROM. Substitute 1.5 Meg of RAM for 128K RAM. 
Substitute a 12 Mhz 68000 for an 8 Mhz 68000. Connect the 
two with the Appletalk serial port. The problem for Apple 
was how the lowly Macintosh could be made to talk to this 
very intelligent device with a minimum of changes to the Mac 
itself. 

The answer was since all Macintosh software writes to 
the screen (and hence the printer via the Print Manager) via 
Quickdraw, those same routines could drive a LaserWriter by 
converting Quickdraw descriptions into POSTSCRIPT. The 
purpose of the Laser Prep file is to convert quickdraw 
commands to POSTSCRIPT. The Laser Prep file is 
downloaded into the LaserWriter as a POSTSCRIPT 
application running within the  LaserWriter. Normal 
Macintosh applications present Quickdraw documents to the 
Printing Manager, which invokes the LaserWriter device 
driver, downloads the Prep File into the LaserWriter 
(Initializing Printer...) which in turn converts quickdraw to 
POSTSCRIPT, which is interpreted by the built-in 
POSTSCRIPT interpreter within the LaserWriter (the 0.5 Meg 
of ROM) and finally converted to a 300 dot per inch page bit 


Mike Schuster wins $50 for the outstanding 
program of the month with this feature article. 
Congratulations Mike! 


map (stored in the 1.5 Meg of RAM not taken up by Laser 
Prep, the POSTSCRIPT page description, and fonts) and 
printed! This double conversion is one reason the LaserWriter 
takes so long to print initially. It also explains why the 
LaserWriter often runs out of memory with some applications 
like Pagemaker, which uses a larger Prep file. In fact, the 
LaserWriter may be even more memory bound than the 512K 
Macintosh, if you can believe that! So limited is memory 
space that the new Laser Fonts from Adobe will probably 
require the new LaserWriter II to be useful, which is supposed 
to have 2 meg of RAM. A conversion kit is rumored to be 
available for upgrading current LaserWriters. 

By sending a POSTSCRIPT file directly to the 
LaserWriter, you avoid having to down load Laser Prep, 
eliminate quickdraw to POSTSCRIPT conversion, free up 
RAM in the printer, and generally speed everything up. Plus, 
you avoid limitations of trying to represent in Quickdraw a 
much more extensive capability of POSTSCRIPT. 
Commands within the POSTSCRIPT file tell the printer that 
the file is to be interpreted and not printed. The fact that Aldus 
Corp. felt the need to write their own Prep File shows the 
limitations of trying to go from Quickdraw to POSTSCRIPT. 
Aldus needed some of the capabilities of POSTSCRIPT that 
the Apple Prep file would not supply. The very thin line in 
Pagemaker is one such feature that could not be represented 
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without a new Prep file. This is not a happy situation since 
now you have two companies supporting two different prep 
file conventions. The smoothing algorithm of Apple is an 
example of how the user is stuck when two companies 
support a competing low level routine. The Aldus Prep file did 
not support smoothing until they had obtained a license from 
Apple. 

Bill Bates of Knowledge Engineering saw all this 
conversion nonsense and recognized that the only way to really 
tap into the power of the LaserWriter was directly via 
POSTSCRIPT. His Just Text and LaserTool products create 
postscript files directly in the traditional typesetting method. 
The advantage of this is POWER. Direct control over every 
feature of POSTSCRIPT, with no Laser Prep quickdraw to 
POSTSCRIPT conversion hassles to slow things down. This 
brings up an interesting confrontation. Aldus follows the 
Macintosh guidelines using Quickdraw and converting to 
POSTSCRIPT. Would it be possible to go the other way and 
create a program that would interpret POSTSCRIPT into 
Quickdraw so that any POSTSCRIPT file could be displayed 
on the screen as a 'soft' LaserWriter Preview? We leave to the 
developer to ponder the implications of such a program. 


POSTSCRIPT EXAMPLE 


Figure 1 shows a drawing created on the LaserWriter by 
the POSTSCRIPT program listing in figure 2. As you can 
see, neither MacWrite, Word or Pagemaker could possibly 
create an image such as this, and yet for the LaserWriter, this 
is a snap! POSTSCRIPT is a programming language very 
similar to Forth. It uses reverse polish notation and a stack 
like Forth does. Arguments are pushed on the stack first, 
followed by the command that executes them. This requires 
the programmer to think backwards in some respects. Adobe 
Systems has just published two very good books on 
POSTSCRIPT programming. They are a tutorial and a 
reference manual, both available in Bookstores from Addison- 
Wesley. Look for a blue and red book under the ttle of 
POSTSCRIPT. This example is taken from the tutorial book 
on page 98. The lines beginning with %% are comments. The 
first line follows the Adobe specifications of %! to tell the 
interpreter within the LaserWriter that what follows are 
POSTSCRIPT commands to be executed rather than a bunch 
of text to be printed. This file can be executed by typing it in 
as a text file with Edit or MacWrite and using the Laser Print 
DA to down load it to the LaserWriter. After using postscript 
directly, I can see that what is now needed is some way that 
artistic POSTSCRIPT programs can be "placed" in page 
makeup programs like Pagemaker so that they can be edited 
and arranged with other text and illustrations. Of course Just 
Text does this, but without the advantage of a screen display 
representation of the final output. Well, enough of the 
introductions to the world of POSTSCRIPT programming. 
Let's get on with solving the hole Apple left us— a utility to 
send POSTSCRIPT files directly to the LaserWriter. Our 
thanks to Mike for this very important and timely article. - 
Ed.] 
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A POSTSCRIPT Server at Work 


When connected to an AppleTalk network, the 
LaserWriter functions as a server for the execution of 
POSTSCRIPT programs sent to it by applications running on 
client Macintosh workstations. The LaserWriter begins 
service by listening for an AppleTalk connection request from 
a client. It then executes the POSTSCRIPT program sent to 
it over that connection. Any error messages or other output 
produced by the program, other than the printed pages 
themselves, are transmitted back to the client over the same 
connection. When the LaserWriter receives an end-of-file 
indication from the client, it sends a matching end-of-file back 
to the client and terminates the execution of the program. 
After receiving the matching end-of-file indication, the client 
closes the connection and frees the server. 

While the LaserWriter is busy servicing one connection, 
it refuses any additional connection requests. This refusal 
causes the requesting clients to queue up and wait for the 
server to become free. As soon as the current connection 
closes, the server accepts the request from the client that has 
waited the longest period of time. [This problem shows that a 
LaserWriter is really of no use to more than one person 
without a File Server to manage this queue of documents. 
Otherwise, everyone on the network sits around waiting for 
the printer to free up before he can get on with his work. 
Which brings us to the next great hole in the Apple Office— a 
file server that spools files to the LaserWriter, allowing 
networked Macintosh computers to do something else after 
clicking print in the File menu! -Ed] 

The communication between the LaserWriter and its 
client workstations is accomplished by means of the 
AppleTalk Printer Access Protocol (PAP). Apple specified 
this protocol in its publications Inside LaserWriter, Inside 
AppleTalk and the AppleTalk Manager chapter of Inside 
Macintosh. [See MacTutor, September 1985 for more on 
AppleTalk programming. -Ed.] 


Calling the PAP Manager 


The Printer Access Protocol Manager provides a set of 
routines which a client uses to communcate with a print 
server. Apple apparently intended that this manager was to be 
used only by the LaserWriter specific portions of the Printing 
Manager, since its documentation is not widely distributed. 
However, the manager does provide an easy way for 
applications to communicate directly with a POSTSCRIPT 
printer. [Apple has not been very forthcoming with any 
printing information on the Mac. -Ed] 

The manager is implemented as a Macintosh device driver- 
like resource PDEF 10 in the LaserWriter resource file in your 
System Folder. The resource contains the implementation of 
the client PAP routines papopen, papwrite, papread, 
papclose, papstatus, and papunload. Before looking at 
the resource in detail, let us consider the functions of each of 
these routines. 

The client application begins by issuing a papopen call 
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9e! PS-Adobe-1.0 
“*% Title: Postscript Example 
%%DocumentFonts: (atend) 

9e9o Creator: Edit 

9e*  CreationDate: 12/27/85 6:21 PM 
9e? oPages: (atend) 
%%BoundingBox: 0 0 612 792 
*%EndComments 


%% Document prolog now follows 
grestoreall 

initgraphics 

/pageproc {} def 

%*%EndProlog 


7676 Postscript Example Program 
%% See page 98 of Postscript Tutorial Manual 


9696 Procedures now follow 


/Times-Boldltalic findfont 
36 scalefont setfont 


/oshow %stack:(string) 
(true charpath stroke) def 


/circleofMacTutor 
(15 15 345 
(gsave 

rotate 0 0 moveto 
(MacTutor) oshow 
grestore 

) for 

) def 


%% Main Program Segment 


250 400 translate 
.5 setlinewidth 
circleofMacTutor 
0 0 moveto 
(MacTutor Journal) true charpath 
gsave 1 setgray fill grestore 
stroke showpage 


%% End of example program 


%æ% Trailer 
*w%Pages: 1 


Figure 2: A Postscript Example for Fig. 1 
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to open a connection with the desired server. The C language 
form of the papopen call is as follows (intl6 is a 16-bit 
signed integer and int32 is a 32-bit signed integer): 


int 16 papopen(refnum, printername, flowquantum, statusbuff, 
compstate) 

int16 *refnum; 

ptr printername; 

int16 flowquantum; 

papstatusptr statusbuff ; 

int16 *compstate; 


Refnum is a pointer to a unique connection reference 
number returned after the connection has been opened. 
Printername is a pointer to the entity name of the server to 
which the connection is to be opened. Flowquantum is an 
integer specifying the size of the receiving buffer provided by 
subsequenct papread calls. Statusbuff is a pointer to a 
status record in which status information is returned to the 
client during the opening process. Finally, compstate is a 
pointer to the integer that the client monitors for call 
completion and error reporting. Its value is positive while the 
call is executing, zero if the connection was opened without 
error, and negative if the connection could not be opened. 

Once a connection has been opened, the application sends 
data to the server by issuing papwrite calls and receives data 
from the server by issuing papread calls. Since the sending 
and receiving data streams are asynchronous with respect to 
each other, the application must be prepared to continuously 
consume data by reissuing papread calls while waiting for 
each papwrite call to complete. If this is not done, deadlock 
may result with the server and client each waiting for the other 
to consume data. 

When all of the data has been sent, the application sends 
an end-of-file indication to the server by issuing a final 
papwrite call. The application must continue to issue 
papread calls until a matching end-of-file indication has been 
received. The application then closes the connection by 
issuing a papclose call. 


The C language form of the papwrite call is as follows: 


int16 papwriteCrefnum, writebuff, datasize, eof, compstate) 
int16 refnum; 
ptr writebuff ; 
int16 datasize; 
int16 eof; 


int16 *compstate; 


Refnum is the connection reference number returned by 
papopen. 

Readbuff is a pointer to the buffer containing the data 
to be sent. Datasize is an integer containing the number of 
bytes in the buffer. 

Eof is an integer containing a non-zero value if an end-of- 
file indication should be sent to the server. Compstate is a 
pointer to the integer that the client monitors for call 
completion and error reporting. Its value is positive while the 
call is executing, zero if the data was sent without error, and 
negative if the data could not be sent. 
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The C language form of the papread call is as follows: 


int16 papread(refnum, readbuff, datasize, eof, compstate) 
int16 refnum; 
ptr readbuff ; 
int16 *datasize; 
int16 *eof; 
int16 *compstate; 


Refnum is the connection reference number returned by 
papopen. 

Readbuff is a pointer to the buffer into which the 
received data is to be placed. Datasize is a pointer to an 
integer in which the number of bytes of data received is 
returned when the call completes without error. Eof is a 
pointer to an integer in which then end-of-file indication 
received is returned when the call completes without error. 

Compstate is a pointer to the integer that the client 
monitors for call completion and error reporting. Its value is 
positive while the call is executing, zero if the data was 
received without error, and negative if the data could not be 
received. 


The C language form of the papclose call is as follows: 


int 16 papcloseCrefnum) 
int16 refnum; 


Refnum is the connection reference number returned by 
papopen. 


At any time, whether or not a connection has been 
opened, the application may issue a papstatus call to find 
out the status of a server. The C language form of the 
papstatus call is as follows: 


int16 papstatus(printername, statusbuff ) 
ptr printername; 
papstatusptr statusbuff ; 


As in the papopen call, printername is a pointer to a 
three-part entity name of the server whose status is to be 
determined and statusbuff is a pointer to a status record in 
which the server's status is returned to the client. The 
structure of the status record is as follows: 


eee struct 
int32 systemstuff ; 


Str255 statusstr; 
) papstatusrec, *papstatusptr; 


Statusstr contains a pascal string and systemstuff 
contains the AppleTalk network address of the server. 


The final manager call, papunload closes all currently 
open connections, terminates all pending papread and 
papwrite calls, and disposes all of the manager's internal data 
structures. The C language form of the papunload call is as 
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follows: 


int16 papunload() 
The PAP Manager Interface 


As I mentioned previously, the client routines of the 
Printer Access Protocol are contained in the PDEF 10 resource 
of your LaserWriter resource file. As illustrated in figure 3, 
the resource begins with entries containing jump instructions 
to each of the client routines, followed by the routines 
themselves. 


A client application calls a routine simply by loading the 
resource, pushing the appropriate parameters on the stack in 
the standard Pascal convention, and calling the appropriate 
entry point using a constant offset from the start of the 
resource. The implementation of this scheme for papopen is 
as follows (in this code, the global variable pap contains a 
handle to the resource): 


int 16 papopen(refnun, printerneme, flowquantum, statusbuff, 
compstate) 
int16 *refnum; 


PAP Manager Structure 


jmp papopen 
jmp papread 


byte 0 
4 

8 

12 

16 

20 


jmp papwrite 


jmp papstatus 


jmp papclose 


jmp papunload 


PAP Manager's routines 


ptr printername; 

int16 flowquantum; 
papstatusptr statusbuff ; 
i *compstate; 


subq. ] 82 AT $ space for result 
move. | refnum(A6),-CA7) % push parameters 
move. | printernameCA6), -CAT) 
move.w f lowquantum(A6),-CA7) 
move. | statusbuff(A6),-CA7) 

] 

1 

1 


move. compstate(CA6), -CA7) 


move. papCA4), Ad $ get handle to resource 
move. CAB), AD % get pointer to resource 
jsr CAB) % papopen entry at offset @ 


move.w (A7)+,DØ % return result 
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The Laser Print Desk Accessory 


The Laser Print desk accessory spools POSTSCRIPT 
programs to a selected printer concurrently with the execution 
of many Macintosh applications. When Laser Print is selected 
from the Apple Menu, it presents a standard file dialog listing 
all of the text files on the current volume. You select the file 
containing the program you wish to send to a POSTSCRIPT 
printer. Laser Print will then send the contents of the file 
incrementally whenever your application calls the Macintosh 
routine SystemTask. Generally, Laser Print should 
continue to operate even if you quit your application and open 
another. 

Before using Laser Print, you should connect your 
Macintosh to the AppleTalk network and choose a 
POSTSCRIPT printer with Apple's Choose Printer desk 
accessory. The POSTSCRIPT programs themselves may be 
either keyed manually (see the example in figure 2), or be 
generated by the Printing Manager itself if you hold down the 
command and F keys just after clicking on the OK button in 
your application's Print dialog. The Printing Manager will 
display the dialog ‘Creating PostScript File’ instead of the 
usual message ‘Looking for LaserWriter.. When your 
application finishes the printing process, you can open Laser 
Print and select the file ‘PostScript.’ 

When Laser Print is opened, its accopen routine is 
called. Accopen presents a standard file dialog and, if a file 
was selected, proceeds to open the file, obtain the resource 
containing the PAP Manager's routines, and then issues a 
papopen call to open the connection to the printer. The 
entity name of the printer selected with Choose Printer is 
contained in the system resource PAPA -8192 (OxE000). 

When Laser Prints routine accctl is called by 
SystemTask, it first checks to see if the connection has 
been opened. If not, accctl simply exits. As soon as the 
connection opens, accctl issues a papread call, reads the 
first 512 bytes of the file and sends them to the printer by 
issuing a papwrite call. Subsequently, accctl issues 
papread calls while waiting for each papwrite to complete. 
When a papwrite completes, accctl reads the next 512 bytes 
from the file and issues another papwrite. 

When accctl has sent the last byte of data, it sends an 
end-of-file indication to the printer. As soon as the matching 
end-of-file has been received, accctl closes itself by calling 
CloseDeskAcc.  Accclose closes the file, the connection, 
and unloads the PAP Manager resource. 

Laser Print itself is complied as a DRVR 25 resource and 
placed in a file of type DFIL and creator DMOV. Hence, you 
can use Apple's Font/DA Mover application to paste the desk 
accessory into your System file. (It will have the familar DA 
icon.) Before you install it, however, use Apple's ResEdit 
application to copy the resource PDEF 10 from the 
LaserWriter resource file into the file containing Laser Print. 
Then change the resource's identifier from 10 to -15574 and 
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name it ‘Laser Print PDEF. Now you must use John 
Mitchell's FEdit application to change two occurances of the 
hex bytes 'A31E' to 'A71E' in the resulting PDEF -15574 
resource. These changes causes the PAP Manager's routines 
to allocate space for their internal data structures in the system 
heap. 

After you have installed Laser Print, you must use 
Apple's ResEdit application to set the 'System Heap' bit of 
both Laser Prints DRVR and the PDEF resources. Even 
though the resource identifiers may have been changed by the 
Font/DA Mover, you should be able to easily find them by 
name. This step is necessary to avoid a system crash if you 
exit your application before Laser Print DA completes it's 
task. [Since both ResEdit and FEdit are necessary utilities to 
complete this application, they are being provided on the 
source code disk #6 along with the Laser Print DA and the C 
source code listed below. -Ed.] 

The remainder of the article contains the C source of 
Laser Print. This version uses header files supplied by 
MegaMax, Inc, version 2.1. You must link Laser Print with 
a slightly modified version of the file 'acc.c. This version 
allocates and maintains a locked area in the system heap for 
Laser Prints global variables. The modifications are as 
follows (lines marked with a + should be added, lines marked 
with a - should be removed; unmark lines are included for 
context only). A complete listing of the acc.c file of desk acc. 
header information is given at the end of this article for those 
converting to another language. 


edd. 1 D4,D0 ,edd size of string space 
* dc.w 0xa722 ;newhandle() & clear to zeros 
- . dc.w 8xa322 ;newhandleC) & clear to zeros 
move. | CAT),A1 ;save in dctistorage 
move. 1] DO, -CAT) ,save result code 
* btst #6,4CA1) ; locked? 
* bne nounlock 
* tst.1 20(A1) 
+ beq nounlock 
move. | 20(A12, AQ 
dc.w 0xa028 jhunlock() the storage 
+ — nounlock: 
move. ] CAT)+, DØ ;result code 
* move. | CA7T)+, AO remove second parameter 
+ move .W DØ, 16CA0) ; force result code 
= eddq. 1 84 AT ,remove second parameter 
move. | DO, -CAT) ,Seve result code 
* btst 36,4CA1) ; locked? 
+  bne nounlock 
* tst.1 20(A1) 
+ beq nounlock 
move. 1] 2ØCA1), AQ 
dc.w Øxaĝð2a ;hunlockC) the storage 
+ noun lock: 
move. ] (AT)*,D0 jresult code 
+ move.] CA7)+, Ad jremove second parameter 
+  move.w DQ, 16CA®) ;force result code 
- . eddq.! 84, AT ,remove second parameter 
move.] (CA7)+,SAVEA4 
/* 


s laser print, version 1.8, Megamax C v2.1 
* a spooler of postscript programs 
x 


* copyright 1985 by mike schuster for MacTutor 
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* all rights reserved 
*/ 


/* macintosh headers */ 

#include <acc.h> /* desk acc. */ 
8include «device.h? /* device managers */ 
8include «pack.h? /* package managers */ 
*finclude <res.h) /* resource manager */ 
* include «toolbox.h? /* toolbox routines */ 


/* n-bit signed integers */ 
"define int16 int 
#def ine int32 long 


/* desk accessory header */ 


( 

0x2400, /* needtime, eccct] */ 
6, /* 0.1 seconds */ 

ø, /* no events */ 

ð, /* no menu */ 

11, /* length */ 

“Laser Print” /* title */ 

) 


"define PAPTYPE "PDEF" /* pap protocal resource type */ 
8def ine PAPID rsrcidC10) /* pap protocal resource id */ 


#def ine ENTITYTYPE "PAPA" /* server entity name res type 
x 


"define ENTITYID 8xe000 /* server entity name res id */ 


typedef struct /* pap status record */ 
int32 systemstuff ; 

cher statusstr[256]; 

) papstatusrec, *papstatusptr; 


int16 dctlrefnum; /* driver reference number */ 


int16 fstate; /* file waiting */ 

int 16 ostate; /* open waiting */ 

int16 wstate; /* write waiting */ 

int16 rstate; /* read waiting */ 

int16 frefnum; /* file reference number */ 
int16 prefnum; /* pap reference number */ 
int16 fres; /* last file result */ 
int16 pres; /* last pep result */ 

int 16 weof ; /* write eof */ 

int16 reof ; /* read eof */ 

char wbuff (512); /* write buffer */ 

char rbuff (512); /* read buffer */ 

int32 fsize; /* file size */ 

int 16 wsize; /* write size */ 

int 16 rsize; /* read size */ 

sfreply reply; /* sfgetfile reply */ 
handle pap; /* handle to pap manager code */ 


handle entity; /* handle to server entity name */ 


papstatusrec status; /* pap status */ 
/* desk accessory open routine */ 
int16 accopen(dctl, pb) 

dctlentry *dctl; 

ji pb; 


/* save driver reference number */ 
dctlrefnum = dctl-— dctlrefnum; 
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/* obtain a postscript program */ 
ree 


/* present standard file dialog */ 
if ClgetfileC&reply)) 

break; 
setcursor(*getcursor(watchcursor)); 


/* open file file */ 
if (fres = fsopen(reply. fname, reply.vrefnum, &frefnum)) 


frefnum = Ø; 
ds 


/* get server entity name */ 

if CICentity = getresourceCENTITYTYPE, ENTITYID)2) 
break; 

hlockCent ity); 


/* get pap manager code */ 

if C!Cpap = getresourceCPAPTYPE, PAPID))) 
break; 

hlockCpap); 

detachresource(pap); 


/* open connection to the server */ 
if (pres = PRFOMSIRSDRAURMM, *entity, 1, &status, &ostate)) 


ostate = Ø; 

break; 

) 
/* file opened and connection opening */ 
fstate = 1; 
wstate = rstate = 9; 


weof = reof = Ø; 
initcursor(); 


/* close down if no file opened or no connection opening */ 
if CIfstate) 
closedeskacc(dct1-? dct refnum); 


return Ø; 


/* desk accessory close routine */ 
int16 accclose(dct], pb) 

dctlentry *dct!; 

ptr pb; 


/* close file if opened */ 
if (frefnum) 
fscloseCfrefnum); 


if P 


/* close connection if opened */ 
if Clostate) 
pres = papclose(prefnum); 


/* unload pep manager */ 
pres = papunload(); 
Sone nee 


return 9; 


/* desk accessory control routine */ 
int16 eccctl(dct], pb) 

dctlentry *dct1; 

Et pb; 
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/* file opened and connection opening? */ 
b 


/* if connection still opening, wait */ 
if Costate > Ø) 
break; 


/* if last papwrite has not finished, or if waiting for a 
match- */ 
/* ing eof indication, continue issuing papreads */ 

if C!pres && Cwstate > Ø || (weof && !reof))) 


if (rstate <= 9) 
if (pres = papread(prefnum, 
&rstate)) 


rbuff, &rsize,  &reof, 
rstate = 9; 


break; 
) 


/* if eny pep call failed or if done, close 
ourselves */ 


if (pres || ostate < Ø || wstate < Ø || Cweof && 
reof )) 
fstate = £; 
closedeskacc(dct]-?dctlrefnum); 
breek; 
/* if last papread finished, start another */ 
if (rstate <= 0) 
if (pres = papread(prefnum, rbuff, &rsize,  &reof, 
&rstate)) 


rstate = Ø; 


/* read more from file, optionally, set eof 
indication */ 
fsize = sizeof wbuff; 
if (fres = fsread(frefnum, &fsize, wbuff)) 
weof = 1; 
wsize = fsize; 


/* send data to server */ 


if (pres = papwriteCprefnum, wbuff, wsize,  weof, 
&wstate)) 
wstate = Ø; 
break; 
) 
return @; 


/* desk accessory prime routine */ 
int16 accprimeCdct], pb) 

dctlentry *dct1; 

d pb; 


return 0; 
/* desk accessory status routine */ 
int16 accstatus(dct], pb) 
dctlentry *dct1; 
ptr pb; 
return £; 
/* return on device driver flavored owned resource id */ 
int 16 rsrcidCid) 
= id; 
pum (CC- dctlrefnum - 1) «« 5) | éxc000) + id; 


/* present the standard get file dialog */ 
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int16 getfileCreply) 
RY *reply; 


point where; 
ostype type; 


where.a.h = 75; where.a.v = 50; 
sfgetfileC&where, "", 81, 1, "TEXT", 81, reply); 
oun reply-?good; 


/* open a connection */ 
int16 papopen(refnum, printername, flowquantum, statusbuff, 
compstate) 

int16 *refnum; 

ptr printername; 

int16 flowquantum; 

papstatusptr statusbuff ; 

int16 *compstate; 


asm 


subq.1  #2,A7 


move. 1 refnunCA6), -CAT) 
move. | printername(A6),-CA7) 
move .W f lowquantumCA6), - CAT) 
move.1 statusbuf f (A62, - CAT) 
move. 1 compstate(A6),-CA7) 

1 


; pap(A42,A8 
move. ] CAD), AO 

jmoveq %'o0', DO 

;dc.w Oxff01 
jsr OCA) 
ee CA7T)+, D8 


) 


/* receive data from server */ 
int16 papread(refnum, readbuff, datasize, eof, compstate) 
int16 refnum; 
ptr readbuff; 
int16 *datasize; 
int16 *eof; 
Ce *compstate; 


asm 


( 

Subq. 82 AT 

move. refnunCA6), -CAT) 
move. readbuf f CA6), -CAT) 


move. eof (46), - CAT) 
move. compstateCA6),- CAT) 
move. pap(A4), Ag 
move. CAO), AD 
;moveq #'r',DØ 
;dc.w üxff01 
jsr 4CA0) 
de (AT)*,D0O 


] 
W 
] 
no datasizeCA6),-CA7) 
1 
] 
] 


) 


/* send data to server */ 
int16 papwriteCrefnum, writebuff, datasize, eof, compstate) 
int16 refnum; 
ptr writebuff; 
int16 datasize; 
int16 eof; 
int16 *compstate; 


asm í 
subq. 1 82 AT 
move.w refnumCA6)2, - CAT) 


move.1 writebuff (A62,- CAT) 
move.w datasizeCA6), -CAT) 
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move .w eof CA62, -CAT) 
move. ] compstateCA6), -CAT) 
move.] papCA4), Aa 
move. | CAD), Ad 
;hoveq #'w' DØ 
;dc.w Oxf fd 
jsr 8C AB) 
"dida (AT)*,D0 


/* obtain server's status */ 

int16 pepstatus(printername, statusbuff) 
ptr printername; 
(ical statusbuff; 


asm 


subq. | 82,A7 
move. | printernameCA6), -CAT) 
move. | statusbuff(A6),-CAT) 
move. | papCA4), Ad 
move. | CAO), AD 
,noveq %'s', DO 
;dc.w Oxff1 
jsr 12CA0) 
Dem (AT)*,D0 


/* close a connection */ 
int 16 papclose(refnum) 
int16 refnum; 


asm 


( 
subq. 1 82 AT 
move.w refnumCA62,-CAT) 
move. | papCA4), Ad 
move. 1 CAB), AB 
,moveq = "'c',D0 
;dc.w OxffO1 
jsr 16CA0) 
"ind CA7)+,DO 


) 
/* unload pap manager */ 
dus ia 


asm 


( 
Subq.1 82 AT 
move. | papCA4), Ad 
move. 1] CAB), AD 
;moveq 8'u' DO 
,dc.w Oxff01 
jsr 20(A0) 
diis CA7)+, D6 


) 


/* acc.c routines modified */ 
define SAVEA4 694 

extern int —GLBLSIZE; 

extern accopen(); 

extern accprime(); 

extern accct1(); 

extern accstatus(); 

extern accclose(); 

—accopen() 


static callacc(); 
int oid; /* owned resource id number */ 


tst.] 20(A1) see if open() already 
called 

beq cont ;do init stuff if not 

pea accopen(PC ) 
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jsr 
addq.1 
unlk 
rts 


cont: 

movem. | 
move. ] 
move. | 
move. | 


move .W 
neg 


as].w 
ori.w 
move .w 


Subq. 1 
move. | 
move 
dc.w 
clr.1 
present 
tst.1 
movea. | 
beq 


subq.1 
move.] 
dc.w 

move. 1 


nodata: 
dc.w 
dc.w 
ext.] 
neg. 1] 
move. | 
add. 1 
dc.w 
dc.w 
nove. 
move. 
nove. 
adda. 
move. 
tst.1 
beq 
move. ] 
move. | 
move. | 
dc.w 
move. | 
dc.w 


— eed eed aed — 


nodata2: 


Subq. 1 
move. | 
move 


dc.w 
tst.1 


-callaccCPC) 
84 AT 
A6 


D1-D5/A2-A4,-CA7) ;save registers 
SAVEAM, -CAT) ,save old M value 


AO, -CATD ¿push parameters for user 
A1, -CATD 

24(A12, DØ ,compute owned resource ID # 
DØ ¿driver refnum = -ID - 1 
subq 81,D0 

#5, DØ 


"üxcO00, DO 
DØ, oid(A6) 


btst 86,4CA1) ; locked? 

bne nounlock 

tst.1 20(A1) 

beq nounlock 

move. | 20(A1), AQ 

dc.w Qxa02a ;hunlockC) the storage 
nounlock: 

move. | CAT)*,D0 ¿result code 

move. | CA7)+,A0 ,remove second parameter 
move.w DO, 16CA0) ;force result code 
move.] CAT)*,SAVEA4 


rada CA7)+,D1-D5/A2-A4 


static .callaccCfunc) 


int (*func)(); 


asm ( 


movem.] D1-D5/A2-A4,-CA7) 


restore registers 


,Seve registers 


84 AT j load in the strings 
8'DATA',-CAT) 

DØ, -CA7) String ID depends on DRVR ID 
Oxa9ad ,getresource() 

D4 ,Sset size to Ø if str res not 
CAT) ,hovea doesn't set cond. codes 
CA7)+,A3 ,handle to string resource in A3 
nodata 

84 AT 

A3, -CAT) 

øxa9a5 ,Sizeresource() 

CAT2*,D4 ,Size of string resource in D4 
9x3a3c jmove.w ®_GLBLSIZE,D5 
-GLBLSIZE 

D5 

D5 ,-GLBLSIZE is negative 

D5, D8 

D4,D0 ,8dd size of string space 
9xal22 ;newhandle() & clear to zeros 
Qxa029 ;hlockC) 

(A72,AÀ1 ,Save in dctlstorage 

A0,20CA1) 

CAO), A4 

D5,A4 ;,M between strings and globals 
A4, SAVEA4 

D4 jif no strings, don't block move 
nodata2 

CA3), AO jStart of string resource 

A4,A1 ,Sirings go above A4 

D4, DØ j length of strings 

0xo02e ;blockmoveC) 

A3, -CAT) ,get rid of the string resource now 
9xa9a3 ;releaseresource() 

84 AT ;Get the init code 


8' INIT',-CA7) 
oidCA62,-CAT) 
,init ID depends on DRVR ID 


0xa9a0 
(AT) 


movea.1 CA7)+,A3 


beq 
existed 


move. | 
jsr 
move. ] 
dc.w 
noinit: 
jsr 
move. | 
move. | 


noinitcPc) 


CA3), A 
CAB) 

A3, -CAT) 
0xa983 


accopen(PC ) 
CA7)+, Al 


DB, -(A7) 


,getresource() 
;movea doesn't set cond bits 
;handle to init resource in A3 
;check to see if init resource 


,execute the init code 


;releaseresource() 


,Sseve result code 
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move.1 SAVEA4,-CA7) 
move .1 A0, -CAT) j last parameter pushed first 
move. | A1,-CAT) 
move. ] 20(A1), AB 
dc.w 0xa029 jhlockC) 
move.1 (A0), A4 ,Sset up A4 globals and strings 
dc.w @x3a3c ,move.w ®_GLBLSIZE,D5 
dc.w ~GLBLSIZE 
neg D5 ;-GLBLSIZE is negative 
adda D5,A4 
move.] A4,SAVEA4 
move. | func(A6), A8 
jsr (A0) ,call user function 
move. 1 CA7)+, A1 ;first parameter device cntr] entry 
move. | D@,-CAT) ,Save result code 
btst 86, 4CA1) ; locked? 
bne nounlock 
tst.1 20(A1) 
beq nounlock 
move.] 20(A1), AQ 
dc.w øxað2a shunlock() the storage 
nounlock: 
move. | CA7)+,D0 ,result code 
move.] (AT2*,A0 ,remove second parameter 
nove.w DØ, 16CA0) jforce result code 
move.] (A7)+,SAVEA4 
movem.] CA7)+, D1-D5/A2-A4 ;restore all saved registers 
) 
bod 
-callaccCaccpr ime); 
-accct1C) 
-calleccCaccct1); 
-BccstatusC) 
-callaccCaccstatus); 
-accclose(C) 
esm ( 
ri A1, -CAT) 
-callaccCaccclose); 
asm ( 
move.] (CA7)+, Al 
move. 1] DØ, -CAT) ,Save result code 
move. | 20(A1), AB ,deallocate global and string space 
dc.w 0xa023 
clr.1 20(A1) ,remove from device contro] 
nove.] (AT)2*,D0 ,restore result code 


= 
p Se 
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Inside Macintosh 


Menu Selection for Desk Accessories 


Writing Desk Accessories with Megamax C 


Writing Desk Accessories is one of the more interesting 
(frustrating?) programming tasks on the Macintosh. I have 
written a number of them using Megamax C, and have found 
it to be an excellent system. There are some things they don't 
tell you in the manual though, which I will point out. This 
article will present a complete working desk accessory in 
Font/DA Mover format. It is modestly complex, and you can 
use it as a shell for your own DA's. 


The dCtlFlags 


Each desk accessory has certain information about it 
stored in a "Device Control Entry" (DCE) when it is opened. 
This includes such things as the driver's reference number, a 
pointer to its window, the number of ticks between periodic 
actions, the menu id, and the dCtlFlags. 

Examine Listing 41. The first thing you see after the 
standard includes is the letters" ACC" followed by some arcane 
numbers. This is a macro for setting the dCtlFlags. The 
Megamax system makes it fairly simple to set up the flags 
properly, with the ACC macro. 

The first number, 0x6400, indicates that this driver needs 
to be locked (all DAs do), will respond to control calls, and 
needs to perform periodic actions. The flags are two bytes in 
length, but only the high order one is used. The bits of that 
byte are defined as follows: 


Bit Number Meaning 

0 dReadEnable - set if 
driver can respond to 
read calls 

1 dWritEnable - set if 
driver can respond to 
write calls 

2 dCtlEnable - set if 
driver can respond to 
control calls 

3 dStatEnable - set if 
driver can respond to 
status calls 

4 dNeedGoodbye - set 
if driver needs to be 
called before the heap 
is reinitialized. 

5 dNeedTime - set if 
driver needs to be 
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Figure 1 Our Desk Accessory Window 


called periodically. 
6 dNeedLock - set if 
driver needs to be 
locked in memory. 


The next number in the header is the number of ticks 
needed between calls (a tick is 1/60 second). Next comes the 
event mask, which is just like an application event mask. 
This program uses OxFFFB which allows all events except 
mouse-up. Next the menu ID, which must be a negative 
number and unique in the system, and finally the title preceded 
by a length byte. The title must be an odd length, add a space 
if necessary. Note that by convention a DA title must begin 
with a zero, or NULL. This is to prevent conflicts with other 
files on the disk which may have the same name as the DA. 


Private Storage 


When you write a DA, you must take care to allocate and 
lock down any private variable storage to be sure that it won't 
move out from under you. The Mac memory manager will 
move things around in the heap as neccessary according to its 
needs of the moment. If you don't lock down your storage, it 
may not be there next time you look for it. 

There are two methods to keep in mind for dealing with 
this situation. 


1. Use auto variables as much as possible, and limit your 
globals to only those that must retain a value between 
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functions. 

2. Define all your globals up front, and then instruct the 
memory manager to lock them down. Be sure to unlock 
and release them when you are done. 


In the DCE there is a space called dCtlStorage, where 
you can store the handle to your private storage area, if any. 
Most systems require that you deal with all this yourself, but 
Megamax C makes it automatic. All global variables are put 
into a DATA segment, which is loaded with the DA at 
runtime. During the open, close, and control calls to the DA, 
this segment is locked in memory, and can be referenced in the 
usual way. The only problem is that nowhere in the manual 
is this explained, or even mentioned. If you attempt to use 
dCuStorage yourself, your DA will bomb inexplicably. Use 
globals, and there will be no problem. In this program, the 
only global is the variable whichstr, which needs to retain its 
value across calls. 


The Five main routines 


There are five basic routines which must be present in 
every Desk Accessory - Open, Close, Control, Status, and 
Prime. The system will pass these routines pointers to the 
Device Control Entry (dctl) and the Parameter Block (pb). The 
Open routine opens the DA and does any initialization. The 
Close routine closes everything and releases all Storage, the 
Control routine takes care of all the various events, the Prime 
routine must implement all read and write calls made to the 
driver (rare for DAs), and the status routine must return 
requested status information (also rare for DAs). Even if you 
do not use all the routines, they must still be defined at least 
as simple returns. In order for Megamax to correctly compile 
your DA, you must name your open routine accopen(), your 
close routine accclose(), your control routine accctl(), your 
status routine accstatus(), and your prime routine accprime(). 


Open 


Examine the accopen() routine now. Notice that the first 
thing it does is check to see if the DA is already open by 
looking for its menu. Under no circumstances must you 
allow the DA to be opened twice! Another way of checking is 
to look at the dCtlWindow field. Assuming that you are 
handling this field correctly (see below), if it is NULL, the 
DA is not open. 


The menu ID method also prevents opening the DA 
should a menu ID conflict arise. Since I have coded the menu 
ID into the DA rather than putting it in a resource, it is 
possible (though unlikely) that some other program will 
already be using that ID. The only way to avoid this problem 
is to put the menu in a named resource, and at run time adjust 
the ID and your code as necessary (see the section on Owned 
Resources below). 

The current Font/DA Mover has a problem with menus, 
SO you cannot be sure that your menu's ID will match up with 
your DRVR ID once it has been installed. Font/DA Mover 
does not properly update the ID numbers of owned MENU 
resources. If you are using GetMenu to get an owned MENU 
resource, you must patch the first word pointed to by the 
returned handle with the actual resource ID of the MENU. I 
have chosen the simplest solution, hardwire the menu ID and 
then check for it before opening. At least there's no way to 
bomb anything with this method, and only in a very rare 
instance would you be unable to open your DA. 

Ok, once you've determined that the Menu ID is 
available, you must check to see if there's enough memory. 
IM says that if there is insufficient memory you should put up 
a dialog that says so. I have settled for a simple beep 

Next, the menu is defined and installed, a window is 
opened and the TextMode and Font are specified. The next 
two lines are quite interesting. 


wp->windowKind = dctl-»dCtlRefNum; 
dctl->dCtlWindow = wp; 


You must set the windowKind field to your driver 
reference number in order for the system to pass you events 
relating to your window, such as a click in the GoAway box. 
This is how the system identifies your window as belonging 
to a DA. You should also put a pointer to your window in 
dCtlWindow. 

Note that you can create your window as a dialog, and use 
the dialog manager routines to control it. I have discovered 
that certain dialog manager routines will not work unless the 
windowKind field is 2 (dialogKind). If you run into this 
problem, just change the windowKind field to 2 temporarily, 
then call the dialog manager, and then change it back to the 
dCtlRefNum when you are finished. This DA is not defined as 
a dialog, so there is no problem. 


Close 


This routine is called when someone clicks the GoAway 
box. Notice how the window pointer is fetched from the 
DCE. 

After zeroing the window pointer in the DCE, the 
window is disposed of, and the menu bar is restored. 

I should mention here that some DAs will need to call 
the close routine before the heap gets reinitialized when the 
user quits an application. If your DA is open when ” 
application terminates and you have files open, you ne 
take care of that stuff before you get blasted away. To 


you must set your flags to indicate that you need a Goodbye 
call, and check for an event code of -1, called the 
GoodByeKiss. Then you can take care of whatever chores you 
have before the DA gets wiped from memory. 


Control 


This routine is called when there is an event your DA 
might have to handle. The event code is passed in the 
Parameter Block. All you need to do is case out on it and 
perform the required actions. This is where you would look 
for the GoodByeKiss, too. 

The only events that this DA looks for are accRun, 
which is called periodically and in turn calls the display() 
routine, and accMenu which has one item which opens a 
dialog box. The dialog template for this DA is in a resource, 
which brings us to the problem of using resources with a DA. 


Owned Resources 


When you create your DA, you can specify the ID 
numbers for the various resources you may wish to use, such 
as a DLOG (dialog template) and DITL (item list) as I have 
done here (see Listing 42). The Macintosh system recognizes 
certain ID numbers as having special significance, and an ID 
code is used to associate owned system resources with the 
resources to which they belong. After all, a desk accessory is 
actually a resource itself, of type DRVR. By using the right 
ID numbers you can tell the system which other resources are 
owned by your DA. 

DRVRs can have IDs in the range 12 to 26. The 
numbers 27 to 31 are reserved for dynamic allocation of IDs at 
runtime for disk drivers, mail servers, etc. For each of these 
ID numbers, there is another unique range of ID numbers that 
is associated with it and that indicate ownership. The formula 
for figuring these out is: 


Resource ID = -16384 + (32'DA ID) + Resource 
number 


All you need to do to assure that the system will 
recognize your DRVR's resources is to give them ID numbers 
in these ranges. Each resource type can include resources in 
these ranges, so you can have, say, a WIND (window) resource 
with ID -16000 and a DLOG (dialog template) resource with 
ID -16000 and both will be associated with the DRVR whose 
ID is 12. You cannot use the same ID number within the 
same type of resource, of course. This means that you are 
limited to 32 resources of any one type. 

An owned resource may itself contain the ID of a resource 
associated with it. For example, a DLOG owned by a DRVR 
contains the resource ID of its DITL (dialog item list). Even 
though the item list is associated with the dialog template, it 
is owned indirectly by the DRVR. Therefor the ID number for 
the DITL must also conform to the same special numbering 
system as the ID of the DLOG. 


Font/DA Mover 


When Apple's Font/DA mover program is used to install 
a desk accessory, it first checks the system file to see what ID 
numbers are already in use for DRVRs. It then changes your 
DRVR‘s ID to one that is not in use, and copies your DRVR 
and its owned resources into the system file. It also changes 
all your resource IDs to conform to the new DRVR ID. If 
you do not follow the numbering convention properly, your 
owned resources will not be copied along with your DRVR, 
causing unfortunate results. 

This has interesting ramifications when you write your 
desk accessory, because there is no way to know beforehand 
what ID numbers your resources will actually have. The 
easiest way I have found to get around this problem is to name 
all of my resources. Resources can also have names in 
addition to their ID numbers, and the names will not be 
changed when the DRVR is copied into the system file. You 
can then use GetNamedResource to find out the actual ID 
number of your resource, as I have done here. 


Display 


The display routine is fairly straightforward, simply a 
series of MoveTo's and DrawStrings. Remember that this 
routine gets called every 20 ticks by the accRun event, and 
uses that to time things. The most interesting routine here is 
the scrolling routine at the end. In order to scroll the bits in a 
given rectangle, you must first create a new region, using the 
NewRgn() call, to hold the update area. This program simply 
discards the region when it's done. Then you can call 
ScrollRect with the rectangle you wish to scroll (in this case 
the whole window), and the direction(s) and amounts. 
Positive numbers produce movement down and to the right. I 
have used a negative vertical movement of 2 pixels each time, 
which results in a smooth scroll upward. 


Creating a Font/DA Mover file 


Once you compile this file, you must then link it. The 
Megamax linker allows you to directly create certain resource 
types. In this case you want a DRVR type resource named 
MTUT, with ID = 12. After the linker is through, you'll have 
a desk accessory ready to run, but there is one problem. 
Font/DA Mover will not recognize the file! The problem is 
that the type and creator are not what Font/DA Mover wants 
to see, even though the file is actually compatible. You must 
use the "set attributes" feature of FEDIT to change the file 
type to DFIL and the creator to DMOV. Then you can install 
the DA with Font/DA Mover. The DA will also take on the 
suitcase icon if Font/DA Mover is present on the disk. 
Recompiling will not change the type or creator, so you only 
need to do this once. 


The RMaker File 


I have provided you with an RMaker file of the DLOG 
and DITL used in this program. Compiling it will add those 
resources to a file named MTUT, which should be your DA's 
name, the file you just linked. I haven't figured out how to 
get RMaker to name resources, so you will need to use 
ResEdit to add the name "MTUTINFO" to the DLOG resource 
before you install the DA. Otherwise the little scheme of 
using GetNamedResource() will not work. If anyone knows 
of a way to get RMaker to produce named resources, please 
write. 

An alternative is to actually create the resources using 
ResEdit, naming them in the process. Frankly, this is the way 
I create all my resources these days, but there is no easy way 
to publish them, since there is no source code generated. 
Guess we'll have to stick to RMaker for exchanging resource 
information. 


Final Notes 


If you follow the basic outline of this DA, you should be 
able to get some of your own up and running. This is not to 
Say that some things about this program couldn't be improved, 
but hey, I'm learning too. I have found that writing DAs is a 
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®include <acc.h> 
include «qd.h» 
*include «mem.h? 
include «misc.h» 
*include «win.h» 
*finclude «te.h» 
include <control.h) 
*include «desk.h» 
®include «device.h» 
*include «dialog.h» 


MegaMax C Source Code 


* include 
t include 
* include 
t include 
include 
tt'include 
* include 
8* include 
8 include 
8include 
*' include 
8 include 


«ctype.t» 
«errno.h? 
«event .h» 
«file.» 
«font.» 
cres. h) 
<menu. h? 
«os.h? 
«pack. h? 


<qdvars.h> 


«seg.» 
«stdio.h» 


Binclude <string.h> 


def ine ENOUGH 93500 
8 def ine MENUID -633 
ACCCOx6400, /* NeedLock,control-enabled,NeedTime */ 
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lot of fun. Just seeing them run concurrently with other 
applications without bombing is a real reward. I hope this 
article helps you along your way. 


" € File Edit View special EVERITT 


MacTutor 
P.0. Box 846 
Placentia, CR 92670 


(714) 993-9939 A 


MacTutor is published monthly to encourage programming FOR the 
Mac, ON the Mac! We are dedicated to the same spirit of knowledge 


that filled the pages of the early Call A.P.P.L.E., Dr. Dobbs, and other 
pioneer technical Journals. 


This Desk Accessory was written by Jan Eugenides, Assembly Corner. 


Figure 3 Our DA has a Menu for an about box! 


20, /* ticks needed */ 
OxFFFB, /* all events except mouseup*/ 
- /* menu id * 


633, 
9, "MMacTutor")/* Length and text of title - must be odd*/ 
int whichstr; /*our only global*/ 


accopen(dct]l, pb) 


dctlentry *dct!; 

pr ence *pb; 
MenuHandle nenu; 
long freemen, grow; 
WindowPeek wp; 
Rect wr; 
MenuHandle testmenu 
Handle rhandle; 
ResType restype; 
char resneme[64]; 
int id; 


e NM = GetMHandleCMENUID)) /*is it open already?*/ 


SysBeep(2); 
one 


else 
/*no, is there memory?*/ 
freemem = MaxMem(&grow); 


MU NEAL 

SysBeep(2); 

return(1); /*no, returnt/ 
) 


menu = NewMenuCMENUID, "MacTutor"); /*install the menu*/ 
AppendMenu(menu, "(-"); 

AppendMenu(menu, "About MacTutor"); 

Inser tMenu(menu, 8); 


DrawMenuBar ( ); 


hichstr = Ø; *initialize counter*/ 
TUUM : IMTUT 
if Cdctl-»dCtlWindow == NULL) /*make a new window */ 
t DLOG 
SetRect(&wr, 20, 40, 274, 240); Spires 
wp = NewWindowCNULL, &wr, "MacTutor", Ø, 22, -1L, -1, ØL); , 
SetPort(wp2; 
TextModeCsrcCopy?; 29 9 332 502 
TextFont(systemFont); Visible NoGoAway 
wo->windowKind = dctl->dCtlRefNum; /* windowkind to refnum*/ 4 
poe = wp; 0 Resources 
return 0; -15999 
) 
accclose(Cdctl, pb) 
dctlentry *dct1; type DITL 
paramblockrec *pb; ae 
WindowPtr tmpwp; 
tmpwp = (WindowPtrOdctl-»dCtlWindow; 
dct1-»dCt Window = NULL; /*clear the window field*/ eu el gt 
if Ctmpwo) DisposeWindowCtmpwp); /*get rid of the window*/ 
Dele teMenu(MENUID); /*and the menu*/ Right On! 
DrawMenuBar (); 
return 6; StatText Disabled 
eccctlCdct], pb) 4 213 19 280 
dctlentry *dct!; MacTutor 
paramblockrec *pb; 
rai tates dnt T" StatText Disabled 
int itemhit; 18 204 33 288 
Handle rhandle; P.O. Box 846 
int id; 
ResType restype; StatText Disabled 
cher resname [64]; 31 177 47 315 
DialogPtr mydialog; 
GrafPtr temport; Placentia, CA 92670 
Switch(pb-?paremunion.CntrlParem.CSCode) /*get control code*/ 
( StatText Disabled 
case accEvent: /*events handled here*/ 47 192 62 300 
break; , 
case accRun: /*called periodically by system*/ (714) 993-9939 
displayCdct 12; /*according to tick count*/ 
break; StatText Disabled 
cese accMenu: 88 8 105 485 
SwitchCitem = (Cint *)&pb->paramunion. Cntr 1Param.csParam)[1]) MacTutor is published monthly to encourage 
en 2: programming FOR the 
GetPortC&temport); 
rhendle = GetNamedResource("DLOG", "MTUTINFO"); StatText Disabled 
GetResInfo(rhandle,& id, &restype, &resname?; 105 8 121 473 
uir Sat NONO OEIC; NM RTOngu ih, Mac, ON the Mac! We are dedicated to the 
etPort(nydialog); irit of k led 
itemhit = Ø; same spirit of Knowledge 
whileCitemhit != 10ModalDialog(Clong20,&itemhit?; 
SetPortCtemport?; StatText Disabled 
DisposDialog(mydialog); 122 9 138 474 
Mii teenucé; that filled the pages of the early 
breek; Call A.P.P.L.E., Dr. Dobbs, and other 
) [fend of menu switch*/ StatText Disabled 
AR 138 8 153 472 
' — [*end of control switch*/ pioneer technical Journals. 
return £; 
/*end of control*/ StatText Disabled 
212 15 250 477 
accprime() /*these are null but must be defined*/ : l 
( P This Desk Accessory was written by 


Jan Eugenides, Assembly Corner. 


oo 
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) 
displayCdct1) /*routine to do the display*/ 
es *dctl; 


Rect wr, drect; 
int i; 

RgnHandle rgn; 

WindowPeek Wp; 

wp = CWindowPeek )dct1->dCt1Window; 


SetPort(wp2; /*set port to our window*/ 
wr = wp-?port.portRect; /*and get the port rect*/ 
whichstr += 1; /*increment string counter*/ 
ifCwhichstr == 47) whichstr = 1; /*enforce limit*/ 
Switch(whichstr) 
( 
cese 1: 
EraseRect(&wr ); /*begin by erasing window*/ 
MoveTo(95, 16); 
TextFaceCbold); 
DrewStringC"MacTutor"); /*put title in boldface*/ 
TextFeceC0); /*restore normal face*/ 
break; 
case 4: 
MoveTo(4 ,32);DrawString("The Macintosh Programming Journal"); 
break; 
case 7: 
Move ToC 12, 48);DrawStr ingC"8-8-8-8-8-8-8-8-8-8-8-8-8"5; 
break; 
cese 19: 
MoveTo(4,68);DrawString("O Programming information!"); 
break; 
case 13: 
MoveTo(4,84);DrawString("o Pascal, C, Assembly, Neon, Basic!"); 
break; 
case 16: 
MoveToC4, 108);DrawString("o Lisp, Modula 2, Forth, and more!"); 
break; 
case 19: 
MoveTo(4, 116);DrawString("0 Technical Information!"); 
break; 
case 22: 
vera 523) Drews UTR Cro The no fluff Macintosh magazine"); 
reak; 
case 25:MoveTo(4, 148);DrawString("o $3Ø/yr US-$45 Canada-$60 foreign"); 
break; 
case 28: MoveTo(4, 164 2; DrewStr ingC "EZZZZZZZZZZ2ZZZZzzzrzzzzzzzzzzzzzzrrz" ); 
break; 
case 31: 
MoveTo(20, 182); 
TextFaceCitalic); 
DrewStringC"PO Box 846, Placentia, CA 92670"); 
TextFaceC0); 
break; 
case 37: 
rgn = NewRgn(); /*we need a new region to scrol1*/ 
for(i = 8;i«95; i++) 

ScrollRect(&wr,0, -2,rgn); /*scroll 2 pixels at a time*/ 
DisposeRgn(rgn); /* done with region*/ 
break; 

default: 


break; 
) /*end of switch*/ 
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C Workshop 
Lost File Finder DA for HFS 


Apple designed the new Macintosh Plus Standard File 
dialog package to provide an easy method for finding files 
nested within the hierarchical file structure of a mounted 
volume. At any given time, the dialog displays a sorted list 
of the files and folders contained within a "current folder". If 
the desired file is not in that folder, and therefore not in the 
displayed list, you must first find the folder that contains the 
desired file. 


If you believe that the desired file is in one of the "sibling 
folders" listed, you select that sibling and click on the Open 
button. The selected folder becomes the new current folder, 
and its contents are displayed. You may have to repeat this 
process if the file is nested several levels deep. 


On the other hand, if the file is not contained within any 
sibling of the current folder, then you choose some "ancestor" 
as a new current folder from the pop-up menu at the top of the 
dialog. You then either select the desired file from the list, or 
repeatedly open sibling and/or ancestor folders until you find 
the file. 


© lost file finder folder 


ay article folder 
System Tools 
() lost file finder 
D lost file finder.c 


D lost file finder.o 


Fig. 1 Moving up to an ancestor 


This manual traversal of the hierarchy can be quite tedious 
if you have forgotten your file's location within the hierarchy. 
It reminds me of an Easter Egg hunt. When working with 
files in several folders, I find it quite easy to accidently save a 
file without noticing which folder the file was placed, 
especially after quickly typing its name and and an Enter key. 
Obviously, some sort of global search function would be 
handy. This is the subject of this month's article. 
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lost file finder 


A User Interface for Global Search 


Here's what I have in mind. As soon as an application 
displays an Open file dialog, I'd like to type the first few 
letters of my file's name. If the file is contained in the current 
folder, an Enter key is sufficently to complete the dialog. 
Otherwise, I'd like to enter some command key combination 
to force standard file to search the hierarchy for a file whose 
name matches the letters I've already typed. 

As soon as standard file finds a candidate, it should 
automatically make the folder containing the candidate the 
current folder as well as select the candidate. At this point, I 
can either accept the candidate by typing an Enter key, or 
resume the search by entering the command key combination 
once again. I'd like to be able to repeat this process until 
either standard file has exhaustively searched the whole file 
hierarchy, or until I find the desired file. 


In retrospect, such a scheme might take a while on a large 
file system, so some way of aborting the search should be 
available. That way, if I get tired waiting, I can always go 
back and hunt for eggs myself. 


A Design using a Dialog Hook 


When I first considered an implementation for such a 
global search, it seemed that rather large changes and additions 
to the standard file package might be required. This turned out 
not to be the case. I was able to implement all of the above 
user interface without any modifications to the standard file 
package using a C language routine passed as the filterProc 
argument to the SFPGetFile trap! 


My filterProc routine implements the search by generating 
a series of "synthetic" events that cause standard file to 
sequentially traverse the file hierarchy until a candidate match 
is found. You can think of it as a simple state machine that 
methodically selects each file and folder from the list one at a 
time in turn. Periodically, the machine uses the Open button 
and pop-up menu at appropriate times to select new folders in 
which to continue the search. As soon as a candidate file is 
found, filterProc stops creating synthetic events and begins 
sending null events through unchanged, allowing the user to 
accept the selection, continue the search, or use any of the 
dialog's buttons and controls in the standard way. 


Rather than generating a sequence of mouse down events 
in the appropriate dialog controls, the filterProc generates the 
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following set of cursor key events, which are understood by 
the new standard file package: 


Function 


Drive Button 
Select next file or folder 


Select previous file or folder 
Open selected folder 


Close opened folder, open parent folder 


Command J 


Command T 


Fig. 2 Command key selections 


Typing a Tab key is equivalent to clicking on the Drive 
button. Typing an down or up arrow key is equivalent to 
scrolling the list of files and folders and selecting the next 
item below, or previous item above in the list, respectively. 
If the currently selected item is a folder, then the Command J 
combination is equivalent to clicking on the Open button. 
Similarly, the Command T combination is equivalent to 
selecting the current folder's immediate parent from the pull- 
down menu. 


In addition to implementing cursor keys, the new standard 
file package dynamically updates the fields of its standard file 
reply record argument while the dialog is open: 


Selection 
Nothing 


File Type Length 


Folder 
File 


Fig. 3 Standard File Reply Record Argument 


If the currently selected item in the dialog is a file, then 
the reply's file type and file name length fields are both 
postive. In this case, the file type field contains the four letter 
finder document type of the file. If the selected item is a 
folder, only the file type field is positive. It contains the 
folder's file catalog directory identifier. Finally, if neither a 
file nor a folder is selected, both the file type and name length 
fields are zero. 


This information, combined with the directory identifier of 
the current folder (which is contained in a low memory global 
location), provide filterProc with just enough information to 
allow it to traverse the hierarchy via a sequence of cursor keys. 
It accomplishes the global search without a single I/O call to 
the file system! One nice side effect of this scheme is the 
animation of the dialog as folders are opened and closed and as 
the item's themselves are selected and scrolled. 
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The "Lost File Finder" Desk Accessory 


The Lost File Finder desk accessory contains an 
implementation of my global search scheme. The accessory 
presents a standard file dialog listing all of the files in the 
current folder. After typing a few letters, you enter the 
Command-space combination to begin (or continue) a search. 
The Command-period combination aborts a search. Since 
standard file displays the last current folder when opening a 
new dialog, you can use the accessory first to find the folder 
containing your file, and then use your application's open 
command to open it. 


The filterProc routine in the accessory is composed of 
three parts. The first parts saves key events in a key buffer. 
This buffer is used to find potential candidate files. The 
second part handles the Command-space and Command-period 
commands. The third part is a simple state machine that 
generates the approprate cursor key events needed to traverse 
the file catalog. 


The state machine is built from three States, named 
NULLSTATE, NEXTSTATE, and SEARCHSTATE. In 
NULLSTATE, null events are sent through unchanged. In 
NEXTSTATE, successive items in the current folder are 
selected. If the selected item is a file, its name is compared 
with the contents of the key buffer. If the selected item is a 
folder, then it is made the new current folder. When the end of 
the item list is encountered, the current folder is closed and its 
parent is opened. At this time, the state machine moves to 
SEARCHSTATE, in which successive items in the parent's 
folder are skipped until the just closed folder is encountered. 
Then the state machine returns to NEXTSTATE, and once 
again begins considering successive items. Of course, the root 
folder is handled as a special case. 


In NEXTSTATE, when a file item is selected, filterProc 
compares its name with the contents of the key buffer. If they 
match, the state machine moves to NULLSTATE, and 
filterProc waits for further input from the user. Otherwise, the 
state machine stays in NEXTSTATE and continues the search. 


The filterProc routine maintains two extra reply records 
named lastreply and startreply. Lastreply contains information 
on the previous item selected. It is used to detect the end of 
the item list, and is required since a | at when the last item in 
the list is selected has no effect. Startreply contains 
information on the item that was selected when the global 
search was begun. It is used to terminate the search when the 
file hierarchy has been completely traversed. 


The accessory accesses three global low memory values. 
ISHFS is nonzero if the Hierarchical File System is installed 
on the Macintosh. 

SFFolder contains the directory identifier of the current 
folder. KEYTHRESH contains the current keyboard repeat 
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threshold value, which is used to flush the contents of the key 
buffer at approprate intervals. 


In addition to these values, the accessory modifies the 
location 


*(int *) (thedialog->refcon - 624) 


where thedialog is a pointer to standard file's dialog 
window. The event record's modifiers field is returned by 
filterProc in this location. The dialog's refcon contains a copy 
of standard file's frame pointer register A6. I discovered the 
proper offset value by disassembling the routine that standard 
file passes to ModalDialog as its own filterProc. 


The accessory will only work with the standard file and 
system folder distributed with the Macintosh Plus. The 
system folder distributed with the original HD-20 apparently 
does not contain the recent extensions to standard file. You 
can use the Mac Plus system folder on an original 512K Mac, 
but not on a 128K Mac. I'm using the system folder 
contained on the "Macintosh Plus Programmer's Package, Mac 
Disk 1, Jan 1986" distributed by Apple at the January 
Developers Conference. It works find in the startup drawer of 
my General Computer HyperDrive internal hard disk. 


The following is the C language implementation of the 
Lost File Finder accessory. Since it contains no assembly 
language routines, it should be easy to port to your personal 
development system. One thing to watch out for, however, is 
that the accessory's open routine closes the accessory with a 
call on CloseDeskAcc. Make sure that your development 
System's desk accessory interface glue can handle this 
gracefully. 


/* 

* lost file finder, version 1.0 

* find lost files with standard file 
x 


* copyright (c) 1986 by mike schuster for MacTutor. 
* all rights reserved. 
*/ 


/* macintosh headers */ 

8include <acc.h) /* This file published last month */ 
*include «dielog.h? 

*include «device.h» 

*Sinclude <event.h> 

include «qdvers.h? 


/* c headers */ 
8include «string.h? 
*Sinclude «ctype.h? 


/* desk accessory header */ 
ACC 


( 
0x0400, /* eccct] */ 
0, /* no seconds */ 
0, /* no events */ 
ð, /* no menu */ 
16, /* length */ 
"Lost File Finder " /* title */ 
) 
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/* standard file key event offset */ 
define KEYOFFSET 4096 


/* states for filtering machinery */ 
"define NULLSTATE Ø 

* define NEXTSTATE 1 

"def ine SEARCHSTATE 2 


/* standard cursor control keys */ 
define NEXTKEY 9x if 

8def ine PREVKEY @xle 

def ine DOWNKEY -@x if 

define UPKEY -øx le 

define HOMEKEY x 1d 

define SEARCHKEY ' ' 

"def ine QUITKEY '.' 


"define isfileCreply) Creply2-?fname[2] 

/* nonzero if file selected */ 
"define isfolder(reply) !Creplyg2-?fname[0] 

/* nonzero if folder selected */ 
"define isnull(reply) C!Creply)->ftype && !Creply2-?fname[0]1) 

/* nonzero if nothing selected */ 
"define ISHFS (*Cint *) Ox3f6 » ø) 

/* nonzero if hfs installed */ 
"define SFFOLDER *Clong *) 8x398 

/* current standard file folder */ 
def ine KEYTHRESH *Cint *) Ox 18e 

/* keyboard repeat threshold */ 
"define ROOTFOLDER 2 

/* directory id of root folder */ 


/* standard file reply typedef, with ftype defined as long */ 
typedef "i 


boolean good; 
boolean copy; 
long ftype; 

int vrefnum; 
int version; 
char fneme[64]; 
) sfreply; 


sfreply reply; /* current standard file reply */ 
sfreply lastreply; /* last standard file reply */ 
sfreply stertreply; /* starting standard file reply */ 
long startfolder; /* starting folder */ 
long searchfolder; /* folder to search for */ 

/* 


int state; current state of filtering machinery 
"f 

define MAXKEYS 24 /* maximum length of key buffer */ 

long keywhen; /* time of lest keydown */ 


cher keys[MAXKEYS + 1]; /* key buffer Cpascal string) */ 


extern boolean getreplyeventfilter(); 


/* desk accessory open routine */ 
int eccopen(dctl, pb) 

dctlentry *dctl; 

d pb; 


point where; 


/* initialize state machine */ 
state = NULLSTATE; 

*keys = 9; 

keywhen = 91; 


/* display dialog */ 

where.a.h = 82; 

where.8.v = 50; 

sfpgetfileC&where, "", 21, -1, 01, 01, &reply, -4090, 
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&getreplyeventf ilter); 


/* close ourselves */ 
closedeskacc(dct1-»dctlrefnum); 


return £; 


/* null desk accessory close routine */ 
int accclose(dctl, pb) 

dctlentry *dctl; 

ptr pb; 


return £; 


/* null desk accessory control routine x/ 
int eccctlCdct], pb) 

dctlentry *dct!; 

per pb; 


return @; 


/* null desk accessory prime routine x/ 
int accprimeCdct], pb) 

dctlentry *dct!; 

p^ pb; 


adi g; 


/* null desk accessory status routine x/ 
int accstetusCdct], pb) 

dctlentry *dct!; 

^u pb; 


return £; 


/* case insensitive pascal string compare, return zero */ 
/* if equal. If prefix is nonzero, then a and b are equal */ 
/* if a is a prefix of b */ 
int pstrcmpCa, b, pref ix) 
register char *a; 
register char *b; 
cs pref ix; 


register int n; 


if (prefix ? *a > *b : *a Iz *p) 
return 1; 
for (n = *at* & Oxff, b**; n && tolower(*at+) == 
tolower(*b**); n--) 


) 
return n; 
) 


/* copy a standard file reply */ 
sfreply *replycpy(a, b) 

sfreply *a; 

(Pp ¥b; 


blockmove(b, a, (long) sizeof(sfreply)); 
return a; 


/* compare two standard file replies, return zero if equal */ 
int replycmp(a, b) 

sfreply *a; 

nep *b; 


return Ca->ftype == b->ftype) ? pstrcmpCa-?fname, b- 
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> fname, Y LE 


/* indicate a failure by sounding off */ 
int failCthestate) 
int thestate; 


sysbeep(4); 
as thestate; 


/* return a key to standard file, and update the current state 
*/ 


int theitemhit(thedialog, itemhit, thekey, thestate) 
windowrecord *thedialog; 
int *itemhit; 
int thekey; 
e thestate; 


/* seve synthetic event modifiers word in proper place */ 
*Cint *) Cthedialog-»refcon - 624) = thekey < Ø ? cmdkey : Ø; 


/* return the desired key with the eppropriate itemhit offset 
?/ 
*itemhit = KEYOFFSET + (thekey € Ø ? -thekey : thekey); 


/* update the current state and return x/ 
State = thestate; 
return -1; 


/* get standerd file reply event filter */ 
pascal boolean getreplyeventf iter Cthedialog, theevent, 
itemhit) 

windowrecord *thedialog; 

eventrecord *theevent; 

(C *itemhit; 


int c; 
die^ Ctheevent-»what) 


case nullevent: 
Switch Cstate) 


/* look for the last opened folder in parent's item 
list */ 
/* change to NEXTSTATE when found */ 
cese SEARCHSTATE : 
if CisfolderC&reply) && reply.ftype == 
searchfolder) 


replycpy(&lastreply, &reply); 
State = NEXTSTATE; 


return theitemhitCthedialog, itemhit, NEXTKEY, 
state); 
break; 


/* search for candidate files */ 
case NEXTSTATE: 
/* handle end of file/folder list */ 
if CisnullC&reply) || IreplycmpC&reply, 
&lastreply)) 
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/* return to first item in list in a flat 
file catalog */ 

if C!ISHFS) 

return theitemhitCthedialog, itemhit, 
HOMEKEY, failCNULLSTATE)); 


/* return to first item in list if in root 
of a hierarchical file catalog */ 
else u CSFFOLDER == ROOTFOLDER) 


if (SFFOLDER == startfolder && 
lreplycmp(&reply, &startreply)) 
state = fail CNULLSTATE); 
replycpy(&lastreply, &reply); 
return theitemhit(thedialog, itemhit, 


) 


/* otherwise return to parent folder and 
search for current folder */ 
else 


HOMEKEY, state); 


searchfolder = SFFOLDER; 
return theitemhit(thedialog, itemhit, 
UPKEY, SEARCHSTATE); 


) 


/* handle a selected file */ 
else if CisfileC&reply)) 


/* check to see if complete catalog was 
searched */ 
if CSFFOLDER == startfolder && 
lreplycmp(&reply, &startreply)) 
state = failCNULLSTATE); 


/* check to see if a candiate was found */ 
else if (!pstrcmp(keys, reply.fname, 1)) 
state = NULLSTATE; 


/* otherwise, continue the search */ 
else 


replycpy(&lestreply, &reply); 

if CisnullC&startreply2) 
replycpyC&startreply, &reply); 

return theitemhitCthedialog, itemhit, 


E 
). 


/* handle a selected folder */ 
else 


NEXTKEY, state); 


/* check to see if complete catalog was 
searched */ 
if Creply.ftype == startfolder && 
lreplycmpC&reply, &startreply)) 
state = failCNULLSTATE); 


/* otherwise, open the sibling folder and 
continue the search */ 
else 


if CisnullC&startreply)) 
replycpy(&startreply, &reply); 
return theitemhit(thedialog, itemhit, 
DOWNKEY, state); 


) 

break; 
default: 

break; 
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break; 


case keydown: 
/* handle keydown event */ 
c = theevent->message & Oxff; 


l /* if not command key, place in key buffer */ 
if C!Ctheevent->modifiers & cmdkey)) 


/* reset buffer if threshold has expired */ 
if Ctheevent- when > keywhen + KEYTHRESH) 
*keys = 9; 


/* add to key buffer */ 
if CC*keys & Oxff) < MAXKEYS) 


keys((*keys & Oxff) + 11 = c; 
(*keys)**; 


/* update time */ 
keywhen = theevent-?when; 


/* handle the initiation of a search */ 
else if (c == SEARCHKEY) 


/* initialize last reply, starting folder and 
reply */ 

replycpy(&lastreply, &reply); 

startfolder = SFFOLDER; 

replycpy(&startreply, &reply); 

/* force nextkey and initialize state machine 
x 


return theitemhit(thedialog, itemhit, NEXTKEY, 
NEXTSTATE); 


/* handle the termination of a search */ 
else if (c == QUITKEY) 
return theitemhitCthedialog, itemhit, NEXTKEY, 
failCNULLSTATE)); 
break; 


return 9; 


A New Standard File 


Since my global search requires the addition of a dialog hook, 
it can't be easily retrofitted into existing applications like 
MacWrite and MacPaint. The obvious solution is to append 
the filterProc code to the end of the standard file package 
resource and insert in the interface the appropriate interface 
calls to it. Of course, if a search capability were build directly 
into standard file, it might be nice, for speed, to avoid the 
dialog animation as the search proceeds. 


Ped 
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Developer's Forum 
Puzzles as Resources in Aztec C 


Polyomino Puzzle Resources 


Synopsis 
Sam Loyd created polyomino puzzles 80 years ago. He 
didnt have a Macintosh, so he made his puzzles out of 
cardboard. I am lucky to own a Mac, so I wrote the game 
MacPoly to draw polyominoes on the screen. 


MacPoly stores polyomino puzzles as resources, in a 
format described in this article. A method for creating these 
resources is presented, enabling you to add your own puzzles 
to MacPoly. The method may also be used to create other 
custom resources. 


Introduction 
The word 'polyomino' is a generalization of 'domino. A 
domino is made of two squares, and a polyomino many 
squares. Here are some polyominoes: 


Monomino 


Triominoes 


Figure 1 


An easy puzzle is shown below. The Object is to cover 
the white square (the solution shape) with the four gray pieces. 
Most polyomino puzzles are much more difficult. 


6 x 6 Square 


Figure 2 
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David Levner 

Sabaki Corp. 

Product : Polyonimo Puzzles 
Contact: (718) 897-1448 


Puzzle Source Files 


The first step in creating a puzzle is to enter a puzzle 
source file. For example, this is the source file I used to 
generate figure 2: 


6 x 6 Square 
Congratulations! Puzzle by David Levner. 
.a.a..58S8SSS..b.b. 
.aaaa.SSSSSS.bbbb. 
aaa..SSSSSS..bbb 
OPE SSSSSS...... 
-C.C..SSSSSS..d.d. 
-cccc.SSSSSS.dddd. 
ccc..SSSSSS..ddd. 
Figure 3 


Use a mono-spaced font, like Monaco to make the 
columns line up, and save the file as text only. The first line 
of the file contains the puzzle name, followed by a 
congratulatory message that is displayed when the puzzle is 
solved. Then begins the puzzle grid. 


The grid contains letters that stand for the squares of 
polyominoes. Lower case letters represent squares that are 
outside the solution shape, and upper case letters, except 'S', 
are squares covering the solution (none are shown in this 
example). Non-alphabetic characters (the dots) are empty 
spaces that are not part of the solution , and the letter 'S' 
denotes the squares of the solution that are not covered by any 
polyominoes. 


Solution Source Files 
The solution to a puzzle is represented by a very similar 
source file. The only difference is that there is no 
congratulatory message. 


6 x 6 Square Solution 


.AAABDB. 
. CACDDD. 
.CCCCDD. 
.CCCDDD. 


Figure 4 
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Puzzle and Solution Resources 


A program could read these source files directly, but that 
would be less efficient than reading resources on the Mac. At 
the end of this article, a program is listed to convert puzzle and 
solution source files into resources. 


MacPoly's puzzles are divided into 9 categories. Puzzle 
resources have type SBPn, where n is a digit from 1 to 9, and 
solutions have type SBSn. 


Besource Type Puzzle Type 

SBP1 Easy puzzles 

SBP2 Rectangles 

SBP3 Almost Rectangles 

SBP4 Parallelograms 

SBP5 Chess Boards 

SBP6 Polyominoes 

SBP7 Chess Pieces 

SBP8 Objects 

SBP9 Impossible Puzzles 
Figure 5 


The puzzle resource for 6 x 6 Square looks like this. 


Congratulations! Puzzle by David Levner. 


.a.a..SSSSSS..b.b. 
.aaaa.SSSSSS.bbbb. 
.aaa..SSSSSS..bbb. 


.c.c..SSSSSS..d.d. 
.cccc.SSSSSS.dddd. 


.a.a..SSSSSS..b.b. 


.aaaa.SSSSSS.bbbb. 
aaa..SSSSSS..bbb. 
RR ENS SSSSSS...... 
.c.c..SSSSSS..d.d. 
.cccc.SSSSSS.dddd. 
COCs Ge ecw ddd 
000000000 
000000000 
999999999 
999999999 
V0 
Figure 6 


The first line of the puzzle source file becomes the 
resource name. The second copy of the puzzle grid reserves 
space to store an arrangement of the pieces saved with 
MacPoly's save command. 


Following the second grid are four nine digit numbers, 
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representing (1) the time spent to arrive at the saved position, 
in seconds, (2) the number of operations performed to arrive at 
the saved position (MacPoly allows you to select a piece, drag 
it, flip it, and spin it), (3) the record time to solve the puzzle, 
in seconds, and (4) the record (fewest) number of operations to 
solve a puzzle. Initially, these numbers are set to O, O, 
999999999, and 999999999. At the end of the resource is a 
binary zero. 


A solution resources differs in several ways: there is no 
congratulations message or timing information, and only one 
puzzle grid. 


Converting Source Files To Resources 


I wrote a C program, called ftor, to convert puzzle source 
files to resources. Ftor is designed to run under a shell 
program; it cannot be run from the Macintosh desktop. If you 
try to recreate ftor, you should run it from the shell supplied 
with your C compiler. 


Most shell programs are modeled on the Bourne shell 
from the Unix operating system. To use a shell, you type a 
command, which is interpreted as a program name followed by 
an argument list. All the C compilers I have seen for the Mac 
include a shell user interface. On the Amiga, Commodore 
supplies a shell called the Command Line Interface. 


I have listed below some dialogs with the shell. The '$' 
is a prompt character, signifying that the shell is ready to 
accept a command. I typed the characters following the '$' to 
run the program ftor; the line below contains the program's 
output. In this case, I ran ftor without any arguments to 
remind me what arguments it expects. 


$ ftor 
usage: ftor TYPE outtile infile1 [infile2 ...] 


Ftors first argument is the four letter type of the 
resource(s) being created, followed by the output file, and one 
or more puzzle source files. Each source file is converted to a 
resource and stored in the output file. 

$ ftor SBP1 Puzzles epz 

Assuming that the puzzle source file of figure 3 is named 
epz, the command above creates a resource called "6 x 6 
Square" in the file Puzzles. The Puzzles file must already 
exist and contain at least one resource. 

Ftor Program Source 
I used Aztec C to compile and link ftor with the following 


two commands: 


$ cc ftor.c -o ftor.o 
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$ In -o ftor ftor.o -lc 


Conclusion 


This article demonstrates a method for creating custom 
resources from ascii source files. Owners of MacPoly can 
create and enter their own puzzles. Puzzles and solutions 
should be entered in pairs; otherwise the Solve feature of 
MacPoly will not work properly. 


Custom resources are both bad and good: few toolbox 
functions can manipulate them, but they do exactly what you 
want. You must write your own code to deal with them, but 
porting the code to other computers will be easier. 


/* The program ftor converts a puzzle source file into a */ 
/* resource. Developed with Aztec C version 1.93. x/ 

/* Copyright Sabaki Corp., 1985, for MacTutor. */ 

/* Note that this is not a stand alone application, but */ 
/* requires the Aztec C system to execute for the */ 

/* default Mac user interface. */ 


include "stdio.h" /* contains definition of NULL (QL) 
x 


"include "ctype.h" /* contains definition of isdigit */ 


/* Quickdraw */ 
/* Memory manager */ 
/* Resource manager */ 


"include “quickdraw.h" 
include "memory.h" 
"include "resource.h" 


[asc 

SS Se ee ee m ee LLlsocc */ 
extern int errno; /* error number variable */ 

Li 

mM ÓÓ—Ó—MÀÀMÀ—À—ÓÀÓ—À — ——ÁÀ—— —À—— ÀÁ—À— À— x/ 


Static long long_type; /* resource type */ 


static char flag puzzle; /* 1 for puzzles, Ø for solutions */ 


mainCargc, argv)  /* Entry point. */ 


int argc; 
char *argv(]); 


/* number of arguments */ 
/* argument vector, an array of strings */ 


int a; /* argument counter */ 

Static char usage_msg[] = 

“usage: ftor TYPE outFile inFilel LinFile2 OU IMS; 

long c4tol(); /* converts four bytes into a long */ 

cher *ctopO, /* converts a C string to a PASCAL string */ 
*ptocC); /* converts a PASCAL string to a C string */ 


if Cargc < 4) 
( printf(usage_msg); exitC1); ) 


long-type = c4tolCargvt 11601, ergvL11L1], ergvE 11(2], 
argvL11[31)5; 

flag-puzzle = Cergv[1)[2] == p gs 
close-application resource. f ile); /* For sefety's sake. */ 
if (OpenResFileCctopCargv[21)) « Ø) /* Open the output f ile. 
*/ 


( 
printf("File $s open error %d\n", ptocCargv[2]), 
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ResError()); 
exitC1); 
) /* then */ 


/* For each input file, add a resource to the output file. */ 
for (a = 3; a < argc; a = a + 1) 
add_resourceCargv[a]); 


exit(0); 
) /* mainc) */ 


static add.resource(f ilename) 
/* Convert one input file to a resource in the Output file. */ 
"ad *filename; /* name of the input file */ 


int data_size, 
source file */ 


/* length of the text in the 


header. size, /* length of text before the 
puzzle grid */ 

resource size, /* length of the resource being 
created */ 

title.size; /* length of the resource name 


char *file data, /* text read from the source 


file */ 

title[80]; /* resource name */ 
Handle res_handle; /* handle to resource being created */ 
Ptr ptr; /* pointer to the resource being 
created */ 


/* Read the input file. Note that if the Second parameter 
*/ 


/* passed to read_file() points to NULL, then read_file() */ 
/* allocates a block of Storage big enough to hold the */ 
/* input file. */ 


file.data = NULL; 
if (read. fileCfilename, &file data) < Ø) 
( printfC"File Zs error Ed. Wn", filename, errno); exitC1); 


for Ctitle.size = Ø; /* Determine the size of the title. 
*/ 

file_dataltitle_size] > «an 

title.size = title size + 1) 


4 


/* Copy title to a C string. */ 
strncpy(title, file data, title_size); 
titleltitle size] = Ø; 


/* Let the length of the title include the \r character. */ 
title_size = title.size + 1; 


/* If @ resource by this name already exists, remove it. */ 
res handle = Ge tNamedResource( long. type, ctop(title)); 
if Cres_handle != NULL) 

RnveResource(res. handle); 


/* Determine the size of the header, the grid, and the */ 
/* resource. The header includes the title and the */ 
/* congratulations message. */ 


header. size = title size; 

While (filedatalheader_size] > '\r') 
header_size = header size + 1; 

header_size = header_size + 1; 


data_size = strlen(file data); 
resource_size = data_size - title_size + 1; 
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/* If it's a puzzle, allow room for a 2nd grid and timing 
info. */ 
if € flag.puzzle ) 
resource size = resource_size + data.size - header.size + 
40; 


/* Get & new handle for the resource. */ 
res handle = NewHandleCClong) resource.size); 
if Cres-hendle == NULL) 
( printfC"Memory error %d\n", MemError()); exit(1); ) 


HLock(res_handle); /* Make sure resource doesn't run off. 
x 
ptr = *res_handle; 


/* Move the header and the puzzle into the resource. */ 
strncpy(ptr, &file_data(title_size], data_size - title_size); 


/* Puzzles include a second puzzle grid, blank timing info. 
x 


ptr = ptr + data_size - title_size; 
if ( flag-puzzle ) 


strncpy(ptr, &file deta[header. size], 
data.size - header. size); 
ptr = ptr + deta.size - heeder. size; 


trepy(ptr, 
"000000000 Vr 000000000 Vr999999999Xr 999999999 r" ) ; 
) /* then */ 
else ptr[ð] = Ø; 


/* Add the resource to the output file. */ 
AddResource(res handle, long_type, UniqueIDClong_type), 
title); 


HUnlock(res_handle); /* Unlock the resource. */ 
free(file_data); /* Free memory allocated by 
read_file(). */ 

return; 

/* static add_resource() */ 

[$= 

—— a ao ww  —— ee ——  — ——— wn  À —  À À— À — = a ae aa am À nn nr Ó  ——M x/ 
long c4tol(cB, cl, c2, c3) 

/* Returns a long constructed from the four bytes. */ 

unsigned char cø, cl, c2, c3; 

returnCCcO. << 24L) + (cl << 16L) + Cc2 «« BL) + c3); 

) /* long c4tol() */ 

feces 
——————————————ÀÀ—————À———————————————ÀÀÀ——--- x/ 


char *ctop(string) 
/* Converts a C string to a PASCAL string, which is returned. 
x/ 


cher *string; 


int length; 
cher *pstring; 


length = strlenCstring); 
for (pstring = &stringllength); 
pstring != string; 
pstring = pstring - 1) 
Xpstring = *(pstring - 1); 
*string = length; 
return(string); 
/* char *ctop */ 


char *ptoc(string) 
/* Converts a PASCAL string to a C string, which is returned. 
x/ 


"ad *string; 


int i, 
length; 


length = *string; 
for Ci = 1; i <= length; i = i * 1) 
stringli - 1] = stringlil; 
stringllength] = 9; 
return(string); 
/* char *ptoc */ 


read. fileCfile.neme, data) 
/* Reads the deta fork of a file. */ 


char *file_name, /* name of the file to be read */ 


; **data; /* pointer to where the file data should go 
x 
( 
int fd, /* file descriptor */ 
size; /* size of the file in bytes */ 


extern long lseek(); 
extern char *malloc(); 


fd = open(file_name, Ø); 
if (fd < Ø) 
return(-1); 


/* determine the size of the file */ 
size = (int) Iseek(fd, ØL, 2); 
Iseek(fd, OL, 8); 


if (*date == NULL) 
*data = malloc(! + size); 
null */ 


/* leave room for a trailing 


if (*data == NULL) 
( close(fd); return(-1); } /* malloc failed */ 


if (read(fd, *data, size) != size) 
( close(fd); return(-1); } /* read failed */ 


close(fd); 
(*deteD[size] = Ø; /* edd a trailing null */ 
return(0); 
/* read fileC() */ 
pec 


close_app1 icat ion_resource_f ileC) 
/* Close the application resource file. */ 


DetachResourceC GetResourceC'CODE', 1) ); 
CloseResFileC CurResFileC) 2; 
return; 
/* close-application resource.fileC) */ 


P 


E 
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Advanced Mac'ing 


Nested Volume Manager DA in Megamax C 


A Nested Volume Manager 


Most third party Macintosh hard disk suppliers provide 
mount manager applications that allow you to partition their 
disks into several logical volumes, all Sharing the same 
Storage medium. These schemes were implemented primarily 
as work arounds for several limitations in the original 
Macintosh File System (MFS). For large volumes, MFS 
suffers from slow file directory searches and poor volume 
space management. Apple's solution to these problems is the 
new Hierarchical File System (HFS), introduced in the Fall 
1985 on its own 20 megabyte hard disk HD20 product, and 
again in January 1986 on its 800k 3.5" disk drive in the 
Macintosh Plus. 

Since HFS provides an better mechanism for handling 
large storage devices, Apple saw no need to implement a 
volume partitioning scheme on its HD20. The HD20 is 
shipped pre-formatted as a single large volume. Other 
suppliers have done the same, such as SuperMac Technology 
for their DataFrame 20 megabyte external SCSI hard disk. 


In this month's article, I 
Show you how you can 
partition your HD20 or other 
third party HFS hard disk into 
independent, variable sized 
nested volumes. Each of these 
volumes is built by creating a 
host file whose contents look 
like a properly formatted MFS 
or HFS volume. Once the 
host file is created and properly 
initialized, its nested volume is 
available on the  Finder's 
desktop and in application's 
open and save MiniFinder 
dialogs just like any other 
ordinary volume. 

Why Use Nested 

Volumes? 

Ive found the "nested 
volume in a host file" 
capability to be useful in a 
variety of ways. You can port 
MFS-only systems, such as 
Apple's MDS and third party 
development systems, onto an 


O The Complete MacTutor, Vol. 2 


Internal Drive External Drive 


EIN Mike Schuster 


Nest Manager Adobe Systems Engineer 
MacTutor Contributing Editor 


HD20 or other HFS disk simply by creating one or more 
MFS nested volumes. (Of course, as development system 
Suppliers release HFS upgrades, this capability will be less 
useful. As of March 1986, the only shipping HFS C 
language systems I'm aware of are Consulair Mac C and 
Megamax C). Another potential use is as a simple volume 
level security system. You might want to associated a 
password with each nested volume, in a manner similar to that 
done by General Computer on its Hyperdrive product. A final 
use is purely academic. The manager provides a good excuse 
for an inside look at the organization of the Macintosh File 
and Disk Driver operating system components. An 
understanding of these components is especially useful now 
with the new opportunities available in the Macintosh Plus - 
SCSI based peripheral market. 
File System and Disk Driver Organization 

The Macintosh File System is the part of the Operating 
System that manages the communication between an 
application and files on a block oriented storage medium, such 
as a hard disk drive. Each Storage medium is formatted into 
one or more volumes, each of which contains some descriptive 


Fig. 1: File System and Disk Driver Organization 


Application 


File Manager 


Apple 
HD20 Disk Driver 


SuperMac 
SCSI Disk Driver 


DataFrame 
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information along with a set of files. 

Before an application can access the files on a volume, 
the volume must be mounted. The File System mounts a 
volume by reading the volume's descriptive information into 
memory and using it to build a new volume control block, 
which is inserted into the volume control block queue. The 
File System performs this mounting process automatically 
both at boot time and whenever a 3.5" disk is inserted into a 
drive. Usually, non-ejectable volumes, such as those on hard 
disks, are always mounted. However, an application may 
direct the File System to mount or unmount any volume at 
any time. The third party mount managers mentioned above 
perform just these functions. 

In order to mount a volume, as well as to access its files, 
the File System must first determine which storage medium 
contains the volume. (Typically, the medium is a disk drive, 
but it may be a section of memory allocated to a RAM disk.) 
Furthermore, once the medium is located, the File System 
must be able to read and write any accessible block on that 
medium. The File System does not do these things itself, 
instead it relies on the drive queue and on a disk driver. The 
drive queue contains one drive queue element for each available 
storage medium. Each drive queue element contains, among 
other things, a drive number uniquely identifying the medium 
and a disk driver number uniquely identifying the disk driver 
program that controls that medium. The drive number of the 
drive containing a volume is also placed in the volume's 
control block. Hence, given a reference to a volume, the File 
System can easily find its corresponding drive queue element 
and the identity of its disk driver. 

Once the File Manager has determined the drive number 
and the controlling disk driver of the medium containing the 
volume, it calls the disk driver to transfer blocks of 512 
characters to and from the device. The disk driver takes the 
positioning information and data from the File System and 
converts them into commands for the disk drive's hardware 
controller and interface electronics. Any resulting data and 
completion codes are returned to the File System when the 
transfer operation completes. The biggest advantage of this 
scheme is that new RAM based disk drivers can be added to the 
system to support new storage media without any 
modification to the fixed, ROM based File System. 

Normally, the drive queue contains one element for each 
physical storage medium connected to the Macintosh, 
including the internal and external drives, RAM disks, and hard 
disks, etc. In the case where several logical volumes share the 
same storage medium, convention dictates that one element be 
placed in the drive queue for each logical volume. This 
convention guarentees that each mounted volume has 
associated with it a unqiue drive number. Although the drive 
queue elements of these volumes have differing drive numbers, 
they all share the same disk driver number. Hence, given a 
drive number of a particular mounted volume, a disk driver 
should be able to determine both the identity of the storage 
medium containing the volume, as well as the location of the 
volume's data within that medium. In the case of a volume 
nested within a host file, this information consists of the 
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drive number of the volume that contains the nested volume's 
host file, as well as the location within the volume of the host 
file's contents. 

Nested Volumes 

Two pieces of software are required to implement nested 
volumes: 

e A mount manager, and 
e A disk driver. 

The mount manager, which I implemented as a desk 
accessory named Nest, presents a user interface that allows 
you to create, mount and unmount nested volumes. The desk 
accessory is responsible for establishing the necessary drive 
queue elements and other data structures that allow File 
System and the disk driver to correctly locate and transfer 
information to and from the volume's host file. For those of 
you familiar with General Computer's Hyperdrive product, 
Nest incorporates the functions of both their Drawers desk 
accessory and their Manager application. 

The second component of the system, the disk driver 
Nest, is responsible for redirecting and translating the File 
System's block level read and write requests to and from the 
nested volume into reads and writes to and from the contents 
of the volume's host file. The driver is shared by all of the 
mounted nested volumes, and uses information defined by the 
desk accessory to associate each volume with the contents of 
its host file. 

When creating a volume, the desk accessory displays a 
standard save dialog allowing you to name the volume, as well 
as specify its size and whether it should be initialized as an 
MFS or HFS volume. In the example below, I show the 
creation of the 800K HFS nested volume Editor. The host 
file containing the new volume, which is also named Editor, 
will be saved in the Nest folder of the volume DataFrame. 
(Normally, the name of a nested volume is the same as the 


Fig. 2: Creating an 800k HFS Nested 
Volume Named Editor 
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Format: (e Hierarchical © Flat 


name of its host file, however, you may later change the name 
of either one in the Finder with no ill effects other than your 
own confusion.) I implemented the dialog's extra buttons and 
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text items in the standard way using the standard file packages 
documented hooks. 

The desk accessory creates the nested volume's host file 
by calling the routine newnest. Its arguments are the file 
name and volume reference number returned by the standard 
file save dialog, along with the desired size of the volume in 
blocks of 512 characters. Newnest first uses the File 
Manager's routine create to create the file, and then the new 
HFS routine alloccontig to allocate the desired number of 
blocks in one contiguous area. Alloccontig is identical to 
the original File System routine allocate, except that if there 
isnt enough contiguous, empty space on the volume to 
satisfy the allocation request, alloccontig will do nothing 
and will return dskfulerr as its function result. By allocating 
the space in one contiguous area, we greatly simplify the 
implementation of the disk driver. 

If the allocation succeeds, the routine seteof is called to 
set the file's logical end-of-file equal to the desired size of the 
volume. Finally, newnest closes the file and flushes the 
volume on which the file resides. If the allocation request 
cannot be satisfied, newnest deletes the file before returning. 
int newnest(fname, vrefnum, blocks) 

char *fname; 


int vrefnum; 
"E blocks; 


long count; 

int frefnum; 

int result; 

/* create and open f ile */ 

fsdeleteCfname, vrefnum); 

create(fname, vrefnum, NESTCREATOR, NESTTYPE); 
fsopen(fname, vrefnum, &frefnum); 


/* allocate contiguous area, save result */ 
count = (long) blocks * 512; 
result = alloccontig(frefnum, &count); 


/* set logical end-of-file */ 
count = (long) blocks * 512; 
seteof(frefnum, count); 


/* close, flush, delete if allocation failed, and */ 
/* return result */ 
fsclose(frefnum); 
if (result) 
fsdeleteCfname, vrefnum); 
flushvol(81, vrefnum); 
return result; 


When mounting a volume, the desk accessory displays a 
Standard open dialog allowing you to select one of the 
previously created host files. In the example below, I show 
the selection of the nested volume contained in the host file 
Editor from the Nest folder of DataFrame. 

In this dialog, the button labeled Mount actually 
Switches between the three titles Mount, Unmount and 
Open. It is Mount if the selected item is a closed host file 
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whose volume is not mounted. It is Unmount if the selected 
item is an open host file whose volume is mounted. Finally, 
it is Open if the selected item is a folder. The New button 
brings up the save dialog discussed above. 

Fig. 3: Desk Accessory file selection 

The desk accessory mounts the volume contained within 
a host file by calling the routine mountnest. Its arguments 
are the file name and volume reference number returned by the 
standard file open dialog, along with the a flag that indicates 
whether or not the volume should be initialized. 

After calling newnest to create a new host file and 
nested volume, the desk accessory assumes you want to 
immediately mount the volume and hence calls mountnest 
directly, rather than displaying the open dialog. In this case, 
the volume needs to be initialized and hence the initialize flag 
is set true. Otherwise, the desk accessory assumes that the 
volume is already initialized and sets the initialize flag false. 

Mountnest begins by opening the file with fsopen 
and determining the size of the volume with geteof. Then a 
new drive queue element is allocated in the system heap. In 
addition to the standard fields, the drive queue elements 
contains a set of custom fields shown in the definition below. 
These fields are used by the disk driver when it translates block 
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level data transfers into operations on the host file. 


/* customized drive queue element */ 
typedef struct _drvqel 


/* standard fields */ 


char dqwriteprot; /* write protected */ 

char dqdiskinplace; /* * 8 for non-eject media */ 
char dqinstalled; /* unused */ 

cher dqsides; /* unused */ 

Struct .drvgel *qlink; /* next drive que element */ 
int qtype; /* unused */ 

int dqdrive; /* drive number */ 


/* disk driver ref number */ 
/* = ® for Mac File System */ 
/* size of volume in blocks */ 


int dqrefnum; 
int dafsid; 
int dqdrvsize; 


/* custom fields */ 
int dafrefnum; 
int dqvrefnum; 
int dadqrefnum; 
int dqdqdrive; 
long dqvstart; 


/* host file reference number */ 

/* nested volume reference number */ 

/* host disk driver ref number */ 

/* host volume drive number */ 

/* host byte position of first block */ 
long dqvmerk; /* host byte position current block */ 
long dqvend; /* host byte position of last block */ 
) drvgel, *drvgelptr; 
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Mountnest then initializes the standard fields of this 
drive queue element. The field dqdiskinplace is set to the 
standard value of 8 to indicate that the volume is non- 
ejectable. This causes the Finder's Eject command and the 
MiniFinder's Eject button to be dimmed when the nested 
volume is selected. 

Mountnest then finds an unused drive number by 
calling the routine finddrvnum and saves the returned value 
in the field dqdrive. Finddrvnum looks at all of the 
existing drive queue elements for an available number. 

Next, the disk driver reference number of the disk driver 
.Nest is saved in the dqrefnum field. The desk accessory 
obtains this value when it opens the .Nest with the call 

opendriver(". Nest", &dqrefnum); 

After initializing the standard fields, mountnest saves 
the file reference number of the volume's host file in the field 
dqfrefnum, the disk driver reference number of the volume 
containing the host file in the field dqdqrefnum, and the 
drive number of the volume containing the host file in the 
field dqdqdrive. The first of these three fields is used to close 
the host file when the nested volume is unmounted. The 
second and third of these fields, which are returned by the call 
to the routine infonest, are used by the disk driver .Nest. 
They allow the disk driver to translate a block level data 
transfer request to the nested volume into a block level request 
to the disk driver of the volume containing the host file. 

Mountnest then determines dqvstart, the byte 
position of the first byte in the first block of the nested 
volume's host file. The value of this field is the key to the 
implementation of nested volumes. Whenever the File 
System requests the first block of a nested volume, the disk 
driver must return the first block of the host file. Similarly, 
when the second block of the volume is requested, the second 
block of the host file must be returned, and so on. Since the 
host files blocks are allocated in one contiguous section on 
the host volume, the disk driver only needs to know the byte 
position of the host file's first block. All other positioning 
can be implemented by adding the appropriate offset to this 
base location. [Remember, we allocated space for this nested 
volume as a continguous section to simplify this operation.] 
This byte position is determined by three values: 

* the number of the first allocation block of the host file, 

e the size of an allocation block on the host volume, and 

e the block number of the host volume's first allocation 

block. 

The first of these values is contained in the 
fcbextrec[0] field of the host file's file control block, whose 
structure is outlined below. The File System maintains one 
file control block for each open file. Given a file reference 
number of an open file, the define FCBPTR returns a pointer 
to its file control block. The second and third of the above 
values are obtained by the File System's routine 
pbgetvolinfo. Hence, the byte position of the host file's 
first block equals the product of the first two of these values 
added to 512 times the value of the third. 

The file control block's fcbextrec field contains the first 
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three file extent descriptors of the open file. A file extent is a 
series of contiguous allocation blocks. Ideally, a file would be 
stored in a single extent, as our host files are, but in general, 
the contents of a file are stored in more than one extent in 
different places on the storage medium. Each extent is 
identified by an extent descriptor, which specifies the number 
of the first allocation block of the extent and the length of the 
extent in blocks. Space on a volume is allocated by the File 
System in units of allocation blocks, each equal to some 
number of 512 character blocks. Hence, fcbextrec[0] and 
fcbextrec[1] form the extent descriptor of the file's first 
extent, where the first field is an allocation block number and 
the second a block length. In a similar manner, 
fcbextrec[2] and fcbextrec[3] describe the files second 
extent; fcbextrec[4] and fcbextrec[5] describe the file's 
third extent, if they exist. Since all host file's are contiguous, 
we only need to be concerned with the value of fcbextrec[0]. 


/* file control block */ 
rd struct 


long fcbF 1Num; /* file number */ 

char fcbMdRByt; /* flags */ 

cher fcbTypByt; /* version number */ 

int fcbSBlk; * first allocation block of file */ 


long fcbEOF; /* logical end-of-file */ 

long fcbPLen; /* physical end-of-file */ 

long fcbCrPs; /* current position */ 

ptr fcbVPtr; /* pointer to volume control block */ 

ptr fcbBfAdr; /* pointer to access path buffer */ 

int fcbF1Pos; /* used internally */ 

long fcbcimpsiz;/* file clump size */ 

ptr fcbbtcbptr; /* pointer to B*-tree control block 
x/ 

int fcbextrec(6); /* first three file extents */ 

long fcbftype; /* file's finder type bytes */ 

long fcbcatpos; /* used internally */ 


long fcbdirid; 
cher fcbcname[32]; 
) fcb, *fcbptr; 
"def ine FCBPTRCrefnum) V 
(Cfcbptr) (C*(char **) x34e) + Crefnum))) 


/* file's parent id */ 
/* name of open file */ 


Once the value of dqvstart is computed, mountnest 
initializes the fields dqvmark and dqvend. These fields are 
used by the disk driver when translating positioning 
information, and correspond to the byte position of the next 
block to be read or written and the position of the byte just 
beyond the end of the host file, respectively. 

Mountnest then inserts the initialized drive queue 
element into the drive queue by calling the routine enqueue. 
Finally, mountnest call the File System routine mountvol 
to mount the volume, unless the volume must be first 
initialized, in which case mountnest calls zeronest. In 
either case, the new drive queue element is ready to provide the 
File System with the information it needs to locate the disk 
driver responsible for data transfer operations. 


int mountnest(fname, vrefnum, zero) 
char *fname; 
int vrefnum; 
int zero; 
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int frefnum; 

int blocks; 

long albiksize; 

int albistart; 
drvqelptr thedrvael; 


/* open file and determine size of volume */ 
fsopen(fname, vrefnum, &frefnum); 
geteof(frefnum, &alblksize); 

blocks = alblksize / 512; 


/* allocate standard drive queue element */ 

thedrvqel = Cdrvgelptr) newsysptr(Clong) sizeofCdrvqe122; 
thedrvqel-?dqdiskinplace = 8; 

thedrvqel-»dqdrive = f inddrvnum( 1024); 
thedrvqel-?dqrefnum = dqrefnum; 

thedrvgel->dqdrvsize = blocks; 


/* customize drive queue element */ 
thedrvgel->dqfrefnum = frefnum; 
infonest(@1, vrefnum, &thedrvqe1-?dqdqrefnun, 
&thedrvqel-?dqdqdrive, &alblksize, &albistart); 
thedrvqel-?dqvstart = FCBPTRCfrefnum)-?fcbextrec[g] * 
albiksize + albistart * 5121; 
thedrvqel-?dqvmark = thedrvge1-? dqvstart; 
thedrvqel-?dqvend = 
thedrvgel->dqvstart + (long) blocks * 512: 


/* enqueue element on drive queue */ 
enqueue(&thedrvqel-»q1 ink, getdrvqhdr()); 


/* optionally zero, then mount volume x/ 
if (zero) 
return zeronest(thedrvgel, fname, putformat); 
else 
return mountvolCthedrvqe1-?dqdr ive, 
& thedrvge1->dqvrefnum); 


When unmounting a nested volume, the desk accessory 
displays a standard open dialog allowing you to select one of 
the currently open host files. The desk accessory unmounts 
the volume contained within the selected host file by calling 
the routine unmountnest. Its arguments are the file name 
and volume reference number of the selected host file, along 
with its file reference number. This latter number is 
discovered with a call to the File System routine 
pbgetfileinfo, which returns, among other things, a file 
reference number if the file is open. 

Unmountnest first calls finddrvqel, which searches 
the drive queue for the element corresponding to the selected 
host file's nested volume. Finddrvqel looks for an element 
with the appropriate disk driver reference number in the 
dqrefnum field as well as a matching file reference number in 
dqfrefnum. Then the File System routine unmountvol is 
called to unmount the nested volume. Finally, the host file is 
closed and the drive queue element is removed from the drive 
queue. 


int unmountnest(fname, vrefnum, frefnum) 
cher *fname; 
int vrefnum; 
int frefnum; 


drvqelptr thedrvqe!; 
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thedrvgel = finddrvgel(dqrefnum, frefnum); 
unmountvol(@1, thedrvqel-?dqvrefnum); 
fscloseCfrefnum); 

dequeueC&thedrvqe1-?q1 ink, getdrvqhdr(C)); 
flushvol(81, vrefnum); 

return £; 


) 


Initializing Nested Volumes 

When a host file is created, its contents must be 
initialized to that of a properly formatted volume before it can 
be mounted. The routine zeronest performs this function. 
Its arguments are a pointer to the volume's drive queue 
element, the volume's name, the a flag indicating whether the 
volume should be formated as an HFS or MES volume. If 
HFS formatting is desired, zeronest simply calls the disk 
initialization package routine dizero. Its arguments are the 
volume's drive number and name. Dizero will first format 
and then mount the volume. (In fact, dizero will HFS 
format only those volumes that are larger than 400k; smaller 
volumes are forced to be MFS.) It is important to realize that 
dizero will call on the disk driver directly to write formatting 
information to the volume. This is ok since the desk 
accessory has already opened the disk driver and mountnest 
has inserted a proper drive queue element into the drive queue. 

If a MFS volume is desired, zeronest writes the 
appropriate information described in the "Data Organization on 
Volumes" section of the "The File Manager" chapter of Inside 
Macintosh. First, the system Startup, master directory, block 
map, and file directory blocks are zeroed with direct write calls 
to the disk driver. Then the volume information area in the 
master directory block is written. The allocation block size is 
chosen to minimize the size of the master directory's block 
map, and then the number of allocation blocks on the volume 
is determined. The constant DRDIRST defines the block 
number of the first block in the file directory. DRBLLEN 
defines the number of blocks in the file directory. Finally, the 
routine mountvol is called to mount the volume. 


int zeronestCthedrvqel, fname, format) 
drvgelptr thedrvqe!; 
char *fname; 
~ format; 


paramblockrec pb; 

int block; 

volinfoptr thevolinfo; 
long size; 


if (format == puthfs) 


dizero( thedrvqel->dadrive, fname); 
return getvinfolthedrvqel->dqdr ive, fname, 
&thedrvgel->dqvrefnum, &size); 


else 


pb.paramunion. ioparam.iorefnum = 
thedrvqe1-?dqrefnun; 

pb.iovrefnum s thedrvqe1-?dqdr ive; 

pb.paremunion.ioparem.ioposmode = fsfromstart; 

pb.paramunion. ioparam. ioposoffset = 91; 

pb.paramunion. ioparam.ioreqcount = 5121; 
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pb .paramunion. n iobuffer = 
newappptr (5 121) 

for (block = DRDIRST * DRBLLEN; block; block--, 
pb.paramunion. ioparam. ioposoffset += 5121) 
pbwrite(&pb, 8); 


thevolinfo = (volinfoptr) 
pb.paramunion. ioparam. iobuf fer ; 

thevolinfo-»drsigword = @xd2d7; 

getdatetimeC&thevolinfo-?drcrdate); 

thevolinfo-»drlsbkup = thevolinfo->drcrdate; 

thevolinfo->dratrb = 9; 

thevolinfo-»drnmfls = 8; 

thevolinfo->drdirst = DRDIRST; 

thevolinfo->drbllen = DRBLLEN; 

thevolinfo->dralbist = thevolinfo-»drbllen + 
thevolinfo->drdirst; 

thevolinfo->dralblksiz = (Cthedrvqel->dqdrvsize - 
thevolinfo->dralblst) / 400) * 10241; 

if (thevolinfo->dralblksiz < 10241) 
thevolinfo-?dralblksiz = 10241; 

thevolinfo->drclpsiz = thevolinfo-?dralblksiz * 8; 

thevolinfo-»drfreebks = thevolinfo-?drnmalblks = 
CCthedrvqel-?dqdrvsize - thevolinfo— dralblst) * 
5121) / thevolinfo->dralbiksiz; 

thevolinfo->drnxtfnum = 11; 

strcpyCthevolinfo-?drvn, fname); 

ctopstr(thevol info->drvn); 

pb. .paramunion. ioparam. ioposoffset = 

pbwriteC&pb, 8); 

disposptr(pb.paramunion. ioparam. iobuf fer); 


10241; 


return mountvolCthedrvqel-?dqdrive, 
&thedrvgel-?dqvrefnum?; 


Nested Disk Driver 

The nested volume disk driver .Nest is built as a 
standard device driver consisting of five routines drvropen, 
drvrclose, drvrcontrol, drvrstatus and  drvrprime. 
Parameters to these routines are passed in standard low level 
parameter blocks, along with a pointer to the driver's device 
control entry, which are both described in detail in the File 
Manager and Device Driver chapters of Inside Macintosh. 

Each of these five routines returns a long result, which is 
rather unusual. The lower 16-bits of this result is the result 
code returned to the Device Manager. The high order bit of the 
upper 16-bits is used distinguished completed I/O requests 
from those that are still pending. In this version of the disk 
driver, all of the requests are completed synchronously, so the 
high order bit is aways set, except for the special case of a 
killio control call. 

The routines drvropen and drvrclose are especially 
simple. They simply return the noerr result code. 

Drvrstatus is a bit more complex. It redirects any 
status calls to the disk driver of the drive containing the host 
files volume. The procedure is quite simple. First the 
argument parameter block is copied into a local variable. 
Then the copy's iorefnum field is changed to the disk driver 
number of the host file's volume, and its iovrefnum is 
changed to the drive number of the host files volume. This 
information is found by searching the drive queue for the 
nested volume's element and uses the information saved in that 
element by the desk accessory when the volume was mounted. 
Next, the redirected request is executed with a call to the 
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routine pbstatus. Finally, the results of the pbstatus call 
are copied back into the proper place in the orginal, argument 
parameter block. 

This scheme of redirecting the requests to the disk driver 
of the host files volume is used in drvrcontrol and 
drvrprime, as well. In drvrcontrol, the calls to format and 
verify the nested volume, and the call to return icon 
information are handled as special cases. The calls to format 
and verify a volume are made by the Finder when its Erase 
Disk command is used. (The first time I tried the Erase Disk 
command on a nested volume, I ended up erasing my whole 
hard disk!) Since we only want the contents of the host file to 
change, not the volume containing the host file, we are careful 
not to forward either of these requests. Drvrcontrol simply 
returns the result code noerr. The third case, when the 
parameter's cscode field equals icondesccode, is the call 
used by the Finder to discover the volume's desktop icon and 
its Get Info information string. This request is redirected, 
and its result, which consist of a single pointer to an an area 
of memory containing an icon, an icon mask, and a pascal 
string are appropriately returned. 

Finally, drvrcontrol intercepts the killio call and 
returns noerr, using the retum macro IORESULT rather 
than IODONE, as required by a warning in the Device 
Manager chapter in Inside Macintosh. 

The heart of the driver is, of course, the drvrprime 
routine. It implements the actual data transfer operations to 
and from the nested volume. With the help of the information 
saved in the drive queue element by the desk accessory, its job 
is relatively straightforward. First it determines which block 
of the volume's host file is to be accessed. It does this by 
checking the positioning information contained in the 
parameter blocks  ioposmod and  ioposoffset fields. 
Depending on the value of ioposmode, drvrprime adds the 
appropriate starting, ending, or current byte position values 
saved in the drive queue element to the value of ioposoffset. 
Then the I/O operation is performed by calling the disk driver 
of the volume containing the host file. Finally, the 
appropriate information is returned in the argument parameter 
block, which consists of the actual number of bytes transfered 
in the ioactcount field, and the new current position, in the 
ioposoffset field. This latter value is also used the current 
position saved in the the drive queue element itself. 

The rest of the source implements the parameter block 
copying and drive queue search utility routines initpb and 
finddrvqel. 

/* 

: Nest Disk Driver 

* Copyright (c) 1986 by Mike Schuster 
a Rights Reserved 


include "drvr.h" 
include "file.h" 
include "nest.h" 
ORVR 


( 
Ox4f 00, 
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: gi (tu 
IN & 


bg 


Nest" 


d 


extern drvgelptr finddrvqel(); 
extern drvgelptr initpbC); 


/* handle open request */ 

long drvropen(thepb, thedct1) 
parambikptr thepb; 
Sd thedct 1; 


return noerr; 


/* handle close request */ 

long drvrcloseCthepb, thedct1) 
paramblkptr thepb; 
(CUN thedct1; 


iai noerr; 


/* handle status request */ 

long drvrstatusCthepb, thedct1) 
parambikptr thepb; 
Coo thedct!; 


paramblockrec pb; 
drvqelptr thedrvael; 


/* initialize parameter block */ 
thedrvgel = initpb(&pb, thepb); 


/* pass on all requests to host */ 
pbstatus(&pb, Ø); 
blockmove(&pb.paramunion.cntrlparam.csparem, 

& thepb-> paramunion.cntrlparam.csparan, 221); 


ad IODONECpb . ioresult); 


/* handle control request */ 
long drvrcontrolCthepb, thedct1) 
paramblkptr thepb; 
E d thedct!; 


paramblockrec pb; 
drvqelptr thedrvqe!; 


/* initialize parameter block */ 
thedrvgel = initpb(&pb, thepb); 


/* handle format code */ 
if Cpb.paramunion.cntrlparam.cscode == formatcode) 
pb.ioresult = noerr; 


/* handle verify code */ 
else if (pb.paremunion.cntrlparam.cscode == ver ifycode) 
pb.ioresult = noerr; 


else if (pb.paramunion.cntrlparam.cscode == killcode) 
return IORESULT(Cpb. ioresult); 


/* handle finder's icon description code */ 
else if (pb.paremunion.cntrlpserem.cscode == 
icondesccode ) 


pbcontrol(&pb, 0); 


*(ptr *) &thepb-?paramunion.cntrlparem.csparam = 
*(ptr *) &pb.paramunion.cntrlparam.csparam; 
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/* pass on all other requests to host */ 
else 


( 

pbcontrol(&pb, 0); 

blockmove(&pb.paramunion.cntrlparam.csparam, 
&thepb-? paremunion.cntrlparam.csparem, 221); 


old IODONECpb. ioresult); 


/* handle read and write requests */ 
long drvrprimeCthepb, thedct1) 
peramblkptr thepb; 
ee thedct1; 


paramblockrec pb; 
drvqelptr thedrvgel; 


/* initialize parameter block */ 
thedrvgel = initpb(&pb, thepb); 


/* remap position relative to start of volume */ 
uus (pb.paremunion. ioparam. ioposmode ) 


case fsfromstart: 
pb.paramunion. ioparam. ioposoffset += 
| thedrvgqe1- dqvstert; 
break; 
case fsfrommark: 
pb.paramunion. ioparam. ioposoffset += 
thedrvqe1-? dqvmark; 
break; 
case fsfromleof: 
pb.paramunion. ioparam. ioposoffset += 
thedrvqe1-? dqvend; 
break; 
case fsatmark: 
pb.paramunion. ioparem. ioposoffset = 
thedrvqe1- dqvmark; 
break; 


pb.paramunion. ioparam. ioposmode = fsfromstart; 


/* perform the request */ 
if Cpb.iotrap & 8x1) 
pbwriteC&pb, 0); 
else 
pbread(&pb, 0); 


/* update current position */ 
thedrvqel-»dqvmark = 
pb.paramunion. ioparem. ioposoffset; 


/* return results */ 

thepb-?paramunion. ioparam. ioactcount = 
pb.paramunion. ioparem. ioactcount; 

thepb->paramunion. ioparam. ioposoffset = 
pb.paramunion. ioparam. ioposoffset - 
thedrvgel->dqvstart; 


iem IODONECpb. ioresult); 


/* find drvqel, given driver reference number and drive number 
x 


drvgelptr finddrvgelCdqrefnum, dqdrive) 
int dqrefnum; 
U^ dqdr ive; 


drvqelptr thedrvqe!; 


for Cthedrvgel = CC(ghdrptr) getdrvqhdr(C22-»qhead; 
thedrvqe] && CDRVQELPTRCthedrvqel)-»dqrefnum != 
dqrefnum || DRVQELPTRCthedrvqel)-»dqdrive != 
dqdr ive); 
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thedrvqel = DRVQELPTRCthedrvgqel2-?qlink) 
return thedrvqel ? DRVQELPTRCthedrvgel) : Øl; 


/* initialize parameter block */ 
drvgelptr initpb(pb, thepb) 
peremblkptr pb; 
peremblkptr thepb; 


drvgelptr thedrvqel; 
*pb = *thepb; 


/* find drive queue element */ 
thedrvgel = finddrvgel(pb->paramunion. ioparam. iorefnum, 
pb- iovrefnum); 


/* install driver reference number and drive number */ 
pb-?peremunion.ioparem.iorefnum = 

thedrvqel-? dqdqref num; 
pb-?iovrefnum = thedrvqel-?dqdqdr ive; 


return thedrvqel; 


The remaining source listed below shows the glue code 
that interfaces the C language implementation of the disk 
driver to the Device Manager. They replace the "acc.h" and 
"acc.c" files in the Megamax C language development system. 
The fundamental difference between these files and those 
provided in the Megamax system is that the IODone routine 
is called appropriately by checking the high-order bit of the 
result returned by the C language routines. — (I hope 
development system suppliers will standardize their interfaces 
so that porting drivers and desk accessories is will become 
easier. The idea of returning a long result originated with Bill 
Croft in his SUMACC C language UNIX-based cross 
development system.) 


/* 
* Driver Interface 
x 


* Copyright Cc) 1986 by Mike Schuster 
* All Rights Reserved 
*/ 


int -ACCDUMMY; 


extern int —drvropen(); 
extern int —drvrprime(); 
extern int —drvrcontrol(); 
extern int —drvrstatus(); 
extern int —drvrclose(); 


define IORESULTCresult) V 
(Clong) Cresult) & 0x0000f fff 1) 
define IODONECresult2 V 
(CClong) (result) & 0x0000ffff1) | 0x800000001) 


define DRVRCF, D, E, M, L, S2 Y 


asm ( V 

dc. F \ 
dcw DW 
dc. E \ 
dc. MW 
dc.w X -drvropent8 V 
dc.w — .drvrprime* 10 V 
dc.w . .drvrcontrol*12 V 
dc.» X .drvrstatus*14 V 

'dc.w X .drvrclose*i6 V 
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/* 
X Driver Interface 


* 


* Copyright (c) 1986 by Mike Schuster 
* A1] Rights Reserved 
*/ 


extern int -GLBLSIZE; 
define SAVEA4 694 


extern int —drvropen(); 
extern int —drvrprime(); 
extern int —drvrcontrol(); 
extern int —drvrstatus(); 
extern int —drvrclose(); 


extern int —~opendrvr(); 
extern int —calldrvr(); 
extern int —closedrvr(); 


extern long drvropen(); 
extern long drvrprime(); 
extern long drvrcontro1C); 
extern long drvrstatus(); 
extern long drvrclose(); 


asm 
-drvropen: 
lea drvropen(PC), A2 
jmp _opendrvr (PC) 
-drvrclose: 
lea drvrcloseCPC2,A2 
jmp _closedrvr (PC) 
_drvrcontrol: 
lea drvrcontrolCPC2, A2 
jmp -cal ldrvr (PC) 
-drvrstatus: 
lea drvrstatus(PC),A2 
jmp _calldrvr (PC) 
-drvrpr ime: 
lea drvrprimeCPC?, A2 
p -calldrvrCPC) 


asm 
( 
-context 
move.] 2ØCA1),A4 ; Actistorage 
move.1 (CA4), A4 ; globals 
dc. w 0x98fc ; Suba.w !! GLBLSIZE,A4 


dc.w -~GLBLSIZE 
move.l A4,SAVEA4 ; save M 


esn 
( 

-opendrvr : 
tst. 20(A1) 
bne .calldrvr 
move. | SAVEA4,-CAT) ; save context 
movem.1 — D4-DT,-CAT) save D registers 
movem.] — A2-A4,-CAT) save A registers 


dctistorage 


we 


we We 


moveq 830 DØ 
dc.w 8x987c 
dc.w _GLBLSIZE 
dc.w 0x8322 
dc.w 0xa029 
move. | A0,20CA1) 


sub.w ®_GLBLSIZE,D# 


we 


newhandleC) 
hlock() 
save dctlstorage 


we We We 
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jsr -context 


move .w 24CA 12,D3 , compute owned resource id 

not.w D3 

asl.w #5,D3 

ori.w *0xc000 ,D3 

Subq. 1 84 AT ; get data 

move. | 8 'DATA',-CA7) 

move.w D3, -CA7T) 

dc.w Üxa9aÜ  ; data = getresourceC'DATA', ownid) 

move. | CA7)+,D8 

beq _nodata 

move. ] 20(A12,A1 ; dctistorage 

move.] DO, AB 

move. ] DO, -CAT) ; Save data 

dc.w £xa9e4 ; handandhand() 

dc.w 0xa9a3 ; releaseresource(data) 
-nodata: 

Suba.1 84, AT ; get init code 

move. | 8' INIT',-CATD 

move .w D3, -CA7T) 

dc.w 8xa9a0 ; init = getresourceC' INIT', ownid) 

move. | CAT)*,DO 


beq -callopen 


move. 1 DØ, A 
move. 1 DO, -CAT) ; Save init 
move. ] (A02, AQ 
jsr (A0) ; call init 
dc.w Qxa9a3 ; releaseresourceCinit) 
bra -callopen 
-calldrvr: 
move. 1] SAVEA4,-CA7) ; save context 
movem.] D4-D7,-CA7) ; Save D registers 
movem.] AQ-A4,-CAT) ; save A registers 
jsr ~context 
-callopen: 
jsr (A2) 
-openrts: 
movem.1 — (A7)*,A0-A4 , restore A registers 
movem.1 (A7)+,D4-D7 , restore D registers 
move. | CA7)+,SAVEA4 ; restore context 
tst.1 DØ ; call iodone? 
bge -calirts 
move. | Ox8fc,-CAT) ; jiodone address 
-callrts: 
tst.w DO ; test result 
rts 
-closedrvr: 
move. ] SAVEA4,-CA7) ; save context 
movem.]1  D4-D7,-(A7T) , save D registers 
movem.] — A0-A4,-(AT) ; save A registers 
jsr -context 
jsr CA2) 
move. | DB ,-CA7) ; save result 
movem. l — (A7),D0/A0-A1 ; restore arguments 
move. 1] 20€A1), A0 , dctistorage 
clr.] 20(A1) , restore dctlstorage 
dc.w 0xa023 ; deallocate 
move .] (AT2*,D0 , restore result 
bra -openrts 
) 


A Few Comments 
I hope this look at the File System and Device Drivers has 
been useful to you. If you have any questions or notice any 
blunders, please send them to MacTutor and I'll try to answer 
or fix them in a future column. The source and object of the 
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nested volume manager Nest as well as the DA and all the 
supporting files are available on source code disk 47 from 
MacTutor's mail order store for $8. Remember, this software 
is only an example, and definitely is not bullet proof. Don't 
try it on a hard disk until you have backed-up its contents. 
Here is the procedure you might use to install it: 

e Use Apple's Font/DA Mover application to copy the 
desk accessory Nest from the Nest suitcase and paste into 
your system folder. 

* Use Apples ResEdit application to copy the .Nest 
DRVR resource from the Nest suitcase and paste into your 
system folder. You may have to change the DRVR's resource 
number before pasting the resource. After pasting the 
resource, set its system heap bit. 

Before using Nest, you should be aware of several 
problems I have discovered while using Version 1.0al on a 
SuperMac hard disk: 

* HFS Systems Only: Nest will run only if the HFS file 
System has been installed on your Macintosh. This means 
that you either own an HD20, a Macintosh Plus, or your third 
party hard disk supplier provided you with an HFS update. I 
have tested Version 1.0a1 on both an HD20 and a SuperMac 
Technology DataFrame 20. 

* Don't Switch Launch: Your system will crash if you 
attempt to switch launch to a different system folder since the 
disk driver .Nest is not detached from the System resource file 
when opened by opendriver. (I consider this an easily fixed 
bug in opendriver.) 

* Don't Mount Non-Contiguous Volumes: Although the 
original allocated host file space is contiguous, it may not 
remain so if you duplicate the file or copy it to another 
volume. (Finder Version 5.2 does not seem to attempt 
contiguous allocations.) The mount manager checks for 
contiguous allocation, but does not attempt to re-copy a non- 
contiguous file to a contiguous area. (This is also an easily 
fixed bug.) 

* Dont Unmount Volumes With Open Files: When 
unmounting volumes, the mount manager does not check to 
see if there exist open files on the volume. If your in the 
Finder, it suffices to drag the nested volume to the trash can. 
The Finder will update the desktop and unmount the volume 
automatically. If you unmount the volume using the desk 
accessory in the Finder, the desktop file may not be correctly 
updated. If you unmount a volume with an open application 
or document file, you'll may crash your System and lose your 
document. 

* Beware of Finder's Erase Disk: The Finder's Erase Disk 
command will format a nested volumes with 400k bytes or 
fewer as an MFS volume; larger volumes will get HFS 
directories. This is done independently of the original 
formatting of the nested volume. 

* Beware of Finder's Trask Can: When you drag a nested 
volume to the trash can, the volume will be unmounted, but 
the volume's host file will not be automatically closed. The 
mount manager will notice this and properly clean up the next 
time it is opened. Aw, 
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C Workshop 


A DA for Mac C without Desk Maker 


Write your Mac C DA's Direct! 

There's a definite problem in developing desk accessories 
with the Consulair Mac C environment: DeskMaker! 

DAs are difficult enough to write without having to 
spend your time with a flaky-pseudo-second-linker to create a 
Font/DA Mover compatible file. While most development 
systems provide compiler and/or linker options to create DAs, 
Mac C must rely on DeskMaker. 

For those of you using assembler, Pascal or perhaps 
another brand of C, let me explain. After you compile and 
link a Mac C program that is to become a desk accessory, you 
must run DeskMaker. Using a standard file dialog, 
DeskMaker asks you for the name of a desk control file. This 
file is a bit like a linker directive, but it specifies such things 
as the DA name, the map file name from the linker, ID, flags 
and other such stuff. After much disk access a DA is created. 

This works but ... DeskMaker will not function correctly 
with the Exec, it gets confused about source and destination 
volumes (worse than RMaker), it does not filter TEXT file 
names in its standard file dialog, you have to create yet another 
directive (aren't link and job files bad enough?), and it's one 
more step to slow down development! 

Mac C is a very good development system, and Consulair 
is constantly upgrading and improving their compiler and 
linker/librarian. They even recently released a disk full of 
useful development utilities. But as of this writing, they have 
not updated or improved DeskMaker. 

I knew there was probably an easier way to develop DAs 
in Mac C, so in January of 1986, I started working on the 
problem. On the following pages I'll show you my 
alternative to DeskMaker and how I developed it. Plus, I'll 
take you step by step through the source code of a real desk 
accessory to show you valuable techniques I learned (the hard 
way) about such things as re-entrancy, menus, memory 
mangement, modal dialogs, and much more. 

This information is applicable to any development 


system, but be warned — some knowledge of 68000 


assembler is needed to fully understand this text. 

Before we get technical, however, I'd like to acknowledge 
a few people whose help made this article and my sanity 
possible during development. While attending MacWorld Expo 
in San Francisco, Fred Huxham and David Burnard (two of the 
authors of an excellent tutorial and reference book called 
"Using the Macintosh Toolbox with C") convinced me my 
crazy idea would work and provided invaluable clues about 
global variables. 

Alan Wooton solved many of my problems before they 
began with his article “A Resource Utility DA with TML 
Pascal" in MacTutor vol. 1, no. 12. He also answered many 
of my silly questions during late-night phone marathons. 
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Figure 1: Clock DA with window, menu, dialog box 


And when I wasn't talking to Alan, Bob Denny told me 
more than I ever wanted to know about device drivers. He also 
confirmed my suspicions about Finder 5.1 (more on this 
later). 

Although I've never met the gentleman, Mike Schuster 
helped shed some crucial light on fooling the compiler. 

Mr. Consulair himself, Bill Duvall, and Jay Friedland of 
technical support were a great source of information and 
confidence, even on Monday mornings. 

Thank you all. Anyway... 

First, a review of the essentials 

A desk accessory is basically one code segment called a 
DRVR resource, although it may “own” other resources such 
as DLOGs, DITLs and MENUs. 

It's a special type of device driver but, like all drivers, it 
begins with a header of information. This header has nine 
elements, each one word in length (a total of 18 bytes). It 
contains, in order: 

e a special 16-bit flag, 

e arate for how often the DA is called by the system, 

* an event mask, 

e a space for a menu ID, 

e and five words of offsets to routines inside the single 

code segment: open, control close, prime, & status. 

Of the five driver routines, only three of these routines 
are usually ever used in a DA: open, control and close. Status 
and prime, the other two routines, are used only by device 
drivers. Open initializes the DA, control is its main loop, and 
close removes it. 

Open is called when the DA is selected from the Apple 
menu. Control is executed while the DA is active, during an 
application's periodic call to SystemTask. Close is called 
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when the DA's close box (or cancel button) is clicked or an 
application calls CloseDeskAcc. 

In addition to the DRVR code resource, there are two 
pieces of data associated with each DA: the parameter block 
and the device control entry. 

The parameter block is a structure allocated by the system 
on the stack, and filled with generally useless information 
except for the csCode and csParam (also called csp). These two 
data are used by the DA to determine what it should do during 
its control routine. A pointer to the parameter block (PB) is 
passed in AO whenever the DA routines are called. 

The device control entry is a structure allocated by the 
system on the system heap, and it's actually very similar to 
the DA header. In fact, the system reads the DA header to 
initialize certain elements of the device control entry (DCE) 
everytime the DA open routine is called. A pointer to the 
DCE is passed in Al whenever the DA routines are called. 

If all this sounds unfamiliar, you might want to review 
the Desk and Device Managers from “Inside Macintosh” before 
you continue. [See also the Assembly Lab article in this same 
issue for more detailed information on the values of csParam 
and csCode. -Ed.] 

DeskMaker Internals 

Now a few more words about DeskMaker and what it 
actually does (without complaining about the way it works). 
Very simply, DeskMaker takes the code created by the linker 
and adds to the beginning of it, in order: a header, the DA ID 
and name, a table of offsets, and a set of “glue” routines to the 
five possible Mac C functions (open, control, etc.). At the 
end of the code, it adds space for any global variables and 
initializes them. It gets the information for the offsets to the 
Mac C functions and the size of the global variable segment 
from the linker map file. The other information, such as the 
flag word of the header, it gets from the desk control file. 

By the way, the glue routines are very necessary because 
the system can't just jump into a normal Mac C function. 
Mac C passes parameters in data registers but on entry a 
pointer to the PB is in AO and a pointer to the DCE is in Al, 
SO an intermediate step is needed to transfer AO to DO and Al 
to D1. Also the control, status and prime routines exit 
differently than open and close, so the glue must provide for 
this. 

The alternative 

When I started this project, I realized that to effectively 
erase DeskMaker I would have to find a way to create the 
header and glue routines during compile and/or link time. I 
then discovered the header and glue could be placed at the 
beginning of a code segment by using inline assembly at the 
beginning of a C source file. This way DC (define constant) 
directives could create the header and a small assembly 
language segment would be the glue. 

So I studied the glue routines Alan Wooton wrote for 
TML Pascal in last November's MacTutor, and with a few 
modifications (Pascal expects parameters on the stack) I got 
his code to work with Mac C. Of course, his code had to be 
included at link time, whereas C allowed this during 
compilation. 


© The Complete MacTutor, Vol. 2 


Now you might think that with the marvelous Consulair 
Linker/Librarian I should have begun working on a library to 
be included at link time rather than do everything in the C 
source file, but my next discovery prevented this. 

As I was staring at my early inline assembly source, it 
struck me that I could place a RESOURCE directive in the 
beginning to change the all code produce by the linker into a 
DRVR of a specified name and ID! Heck, I could even preset 
it as purgeable this way. When balanced with a /Resources 
command in the linker directive, it worked perfectly ... 
almost. 

Because the RESOURCE directive will not allow a null 
byte (ASCII zero) to precede the name parameter, the format of 
the name was not correct for a desk accessory. "Inside 
Macintosh" says all drivers must have a single character 
preceding their name to prevent confusion with filenames. 
This character is a period for device drivers and a null byte for 
DAs (hex zero). 

However, I was delighted to discover that if a DA has this 
incorrect name format, Font/DA Mover will add the null byte 
whenever it's moved into another file. Also, ResEdit will 
allow you to fix the name. Various DA sampling utilities, 
such as Loftus Becker's DA Key, don't mind it being incorrect. 

Even though this deficiency in the RESOURCE directive 
seemed a moot point, I mentioned it to Bill Duvall. He told 
me it will be modified sometime, probably this year. 

Anyway, now I could create a DA in a single C source 
file and linker directive. By using the /Type command in the 
linker I could even make it a Font/DA compatible file. The 
next big problem to tackle was global variables. 

Applications reference their globals via negative offsets 
to A5. DAs should NEVER use AS for their globals. So 
Mac C has a compiler option to set the global index register, 
and when using DeskMaker, you set this to A4. Before the 
glue routines created by DeskMaker call any C functions, A4 
is set to point to the end of your code where the globals were 
added. This is nice because you get to declare your globals in 
a desk accessory the same way you would in an application. 
The thing I don't like about it is where the storage is placed. 
Not only is modifying data in a code segment (even if its at 
the end of that segment) a dangerous practice, but large 
uninitialized global structures allocated inside the code waste 
space. 

Since I very rarely initialized any of my globals during 
compilation, I decided that I should allocate them at runtime. 
At first I adapted Alan Wooton's method. 

During my C open function I created a relocatable 
Structure on the heap and stored a handle to it in the 
dCtlStorage field of the device control entry. That's one of the 
suggested uses for dCtlStorage anyway. Remember, all new 
relocatable structures are not purgeable, so there was very little 
chance of my globals disappering on me. Whenever I needeed 
to reference the globals, I retrieved the handle via the DCE, 
locked it, dereferenced it into a pointer, and then passed that 
pointer to any subroutines that needed to access the globals. 
When it was no longer needed I simply unlocked it, and on 
exit, my close routine disposed of the storage. 
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I liked the idea of breaking the DA into smaller pieces so 
they could float around the heap when inactive (In case you 
didn't know, the DA code itself is usually locked on the heap 
by the system whenever the DA is called, and unlocked when 
the DA returns control to the system). This allocation 
technique also allowed the globals to be as big as 32K in 
memory and exactly OK in the system file. 

However, the Macintosh is hard enough to program 
without having to induce even more pointer indirection inside 
the C source. Not only is it maddening to remember to get 
pointers to pointers, but the extra typing alone will give you 
arthritis. All this plus passing an extra parameter to 
subroutines generated a lot of extra code. Maybe this is 
palatable in Pascal but I needed a better way to reference my 
global storage in C. 

I wanted to be able to declare global variables as you 
would in any C program. Since DeskMaker set up A4 to 
point to the globals in its glue routines, I figured on trying 
the same strategy. Of course this also meant I'd have to 
allocate my storage during the glue and use the compiler 
option to set the index register to A4. 

This worked fine but everytime I changed the size of my 
variable structure, I had to modify the assembly source which 
called NewHandle with a specific size constant. As you can 
imagine, this got to be a real problem when I'd forget to 
change it or simply not calculate the constant correctly. 

I wanted a way to have the compiler to calculate the value 
of the global size. As it turned out though, I had to trick the 
compiler and use the linker to make the calculation. The 
technique is a little strange but it works. 

First, you have to remember that a global variable 
declaration creates an offset value to whatever index register is 
used as a global pointer. The actual offset values for globals 
are completely unknown to the compiler, as are any other 
addressing offsets. The correct offset values are resolved and 
inserted in the code by the linker. Variable offsets are resolved 
as negative values, and the first variable declared has the 
largest offset. 

Since the assembly language equivalent of a Mac C 
global declaration is achieved with the DS directive, I used this 
in my header/glue source to declare a zero length variable 
called globalSize before declaring any globals in my C source. 
Having no length, globalSize was resolved as the same value 
as the first C global variable. This meant I could simply 
move globalSize into a register, negate it to make it a positive 
value, pass it to NewHandle, lock the storage, dereference the 
handle to a pointer in A4, and add globalSize to A4 which 
then decremented A4. Simple? Right. 

Unfortunately the compiler generated all sorts of rude 
errors when I included the following instruction: 

MOVE.Wé#globalSize,DO 

I was emotionally crushed. Two days later I happened to 
be thumbing through Mike Schuster's nifty article on the 
Laser Print DA in MacTutor vol. 2 no.2, when I noticed he 
had a listing for a modified version of some DA glue routines 
for Megamax C. Incredible! He was doing the very same 
thing, but he had managed to get it by the compiler. I used 
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his technique to do this: 

DC.W $303C 

; This is the value of the machine instruction for a MOVE.W 

; to place the following word in memory into DO. 

DC.W globalSize 

; This (the following word in memory) is resolved by the linker! 

Sure, it may be a kludge but it always works. 

Later I was told that a LEA globalSize,An instruction 
would also get the value. Not only does this take a few more 
bytes in memory to transfer the value from an address register 
into DO, it has the severe handicap of not working. All it 
does is get the PC relative offset to the beginning of the 
header. Suprisingly, the first time I tried this my DA didn't 
crash, instead it allocated over 20K on the heap for two 
pointers and an integer. 

By the way, the linker directive needs to set global 
allocation to -0 or similar allocation problems can occur. 

After finally getting globals to work, I realized I ought to 
optimize the glue routines to get rid of repetitive instructions. 
Instead of having a separate glue routine for open, control and 
Close, I wrote one main code segment that is used in every 
call. This is similar to Bill Duvall's method used in the 
DeskMaker glue. 

Open and close don't need to preserve as many registers as 
control, but since they all travel the same road, I saved D4- 
D7/A0/A1/A4-A6 on entry and restored them on exit. Mac C 
will actually preserve AS and A6, but it's possible an 
assembly language subroutine could trash them. It never hurts 
to be safe. 

Originally I wrote a lot of error checking for the glue, but 
in the end I decided to just exit open if I couldn't allocate the 
space for globals. The reason I don't check for errors, after I 
use HLock and HUnlock on the storage, is because there's not 
much you can do if some other task has messed up the 
globals. If the heap gets that damaged, a system error is 
inevitable. 

DAs should return a result code in DO after every call. 
This result is read by the system, but unfortunately it's not 
preserved for the current application. To get around this bug I 
placed the result in the ioResult field of the parameter block 
on exit. 

After finishing the header and glue I realized they were 
taking up about two pages at the beginning of my C source. 
It was when I decided to include them as a separate file that I 
got the idea for writing a macro. Wouldn't it be nice to 
configure the DA name, ID, flags and other stuff with just one 
line of text inside a Mac C source file? Now you can do this! 

If you take the time now to examine listings 1 and 2, 
you'll see the final outcome of my project. 

Listing 1 is a file called DeskAccessory.c. This is 
included in the beginning of a Mac C source file along with 
all the other headers. It contains a single assembly language 
macro called DeskAccessory. This macro configures and then 
includes the file shown in listing 2, DAHeader.asm. You can 
invoke the macro using this format: 

#asm 
DeskAccessory 'Name',ID,Flags,Rate, EvtMask,Globals 
#endasm 
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That's all there is to it! 

As you can see, the macro has six parameters. The first 
(always enclosed in single quotes) defines the name of the desk 
accessory and the second its resource ID (12-31 inclusive). 
The third, fourth and fifth parameters define constants in the 
DA header (more on these later). The sixth parameter is a 
conditional request for global variables to be allocated at 
runtime, and it takes only two arguments: NeedGlobals or 
NoGlobals. 

If you examine DAHeader.asm in listing 2, you'll notice 
it has conditional assembly statements. This conditional 
assembly is dictated by the sixth parameter of the macro. The 
reason I did this is to save code space. Why mess with handles 
and pointers if you don't need globals? 

So, if you want the code to handle global variables in 
your DA, specify NeedGlobals as the sixth parameter of the 
DeskAccessory macro. If you're not going to use any global 
storage, specify NoGlobals. Simple. 

However, there are four very important things to 
remember if you use this macro: 

Always invoke the macro before you declare any global 
variables or define any Mac C functions! If you do specify 
NeedGlobals, use the compiler option to set the global address 
register equal to A4 or a system error will occur at runtime. If 
NeedGlobals is specified and no global variables are declared in 
the following C source, a system error is very likely at 
runtime. Finally, all global variables are initialized to zero. 

The flags, delay and event mask parameters can be written 
in whatever number format you're used to, but remember that 
C and assembler number formats are not the same. 

Although the 16-bit flags contain bits that can be set to 
enable read, write and status calls, these bits are always cleared 
in DAHeader.asm. I did this because these three bits are only 
relevant to device drivers with status and prime routines. The 
header expects to find three functions in the C source: open, 
control and close (all in lowercase), and it will not recognize 
Status and prime. 

In conclusion... 

Well, I managed to duplicate most of the functions of 
DeskMaker exept its ability to test the DA after linking. 
Shucks. I use Loftus Becker's DA Key for this purpose — a 
utility I recommend highly. It's also more stable than 
DeskMaker's testing function anyway. I also recommend 
testing any DAs you might write while operating ResEdit, a 
very harsh environment. ResEdit does many interesting 
things to the heap, like moving nonrelocatable blocks. 

Now take some time and read listing 3. It contains the 
complete source to a clock DA plus an incredible number of 
useful comments. The listing is designed to be read from start 
to finish, and the comments are placed in front of each 
function to make the source itself more legible. A few of 
these comments repeat themes discussed by Alan Wooton in 
previous issues of MacTutor, however they are repeated here 
for completeness and clarity, and many of them have been 
expanded. 

Using the clock DA as a model, you can write a desk 
accessory which will survive the most brutal test that I know: 
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running under TMON with heap check, scramble and purge all 
enabled! Many applications can't even stand that. 


/* Filename: DeskAccessory.c compiled with Mac C 4.0 */ 


DESK ACCESSORY MACRO 
version 02/26/86 


Copyright (021986 by Don Melton, all rights reserved. 


This file is included in a Mac C source file in order to 
invoke the DeskAccessory macro later in that source file. This 
macro must be invoked before declaring eny global variables or 
defining any Mac C functions. */ dE 


"asm 
noGlobals SET Ü 
needG lobals SET 1 
MACRO DeskAccessory da1,da2,da3,da4,da5,da6 = 
daName SET (da 1} 
daID SET (da2) 
daF lags SET (da3) 
deServiceRate SET (da4) 
daEventMask SET (da5) 
needGlobals SET (da6) 
INCLUDE DAHeader . asm | 
"'endasm 
Listing 1 
Listing 2 


; Filename: DAHeader.asm originally compiled with Mac C 4.0 


;DESK ACCESSORY HEADER 
, version 02/26/86 


; Copyright (021986 by Don Melton, all rights reserved. 
; This file is configured and included in a Mac C source file 


by 
; Invoking the macro called DeskAccessory defined in 
; DeskAccessory.c. 


; EQUATES 

.TRAP — -NewHandle $4122 ; defined in SysTraps. txt 
.TRAP — .DisposHendle $4023 

.TRAP = .HLock $4029 

„TRAP — _HUnLock $402A 

clear SET $200 


dCtlStorage SET $14 


; defined in SysEqu.d 
dCtlWindow SET $1E 


ioResult SET $10 
jl0Done SET $8FC 
daF lagMask SET $F 4FF 


; GLOBAL VARIABLE DECLARATION 
globalSize DS " 
XREF globalSize 


4 
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; LINKER DIRECTIVE 
RESOURCE 'DRVR' daID daName 32 


DC.W daF lags & daF lagMask 

; Clear dReadEnable, dWritEnable and dStatEnable 
DC.W daServiceRate 
DC.W daEventMask 
DC.W Ø 

DC.W de0pen 

DC.W Ø 

DC.W daControl 
DC.W Ø 

DC.W daClose 


; space for menu ID 
; no prime 


; no status 


; GLUE ROUTINES TO MAC C FUNCTIONS 
; On entry AB contains *PB (pointer to parameter block) and 
; Al contains *DCE (pointer to device control entry). 


daQpen: 
PEA open ; Mac C function 
BRA.S nain 
daClose: 
if needGlobals 
PEA disposeGlobals ; intercept routine 
else 
PEA close ; Mac C function 
endif 
BRA.S main 
daContro] : 
MOVE.L jl0Done, -CSP) ; jump vector 
PEA contro] ; Mac C function 
main: 
if needGlobals 
MOVEM.L D4-D7 /A0/A1/A4-A6, -CSP) ; Seve registers 
MOVEA.L dCtiStorage(Al),A® ; get handle 
MOVE.L A2,D0 ; empty handle? 
BNE.S lockGlobals ; no, lock globals 


; allocateGlobals 
CLR.L DO ; clear high word 
; Since MOVE.W "globalSize, DØ causes an error ... 


DC .W $303C ; kludge instruction 
DC.W globalSize resolved by linker 
NEC .W DO ; make it positive 
-NewHandle ,clear 
BEQ.S initGlobals ; if no error, init 
MOVE.W #$-1,DØ ; error result 
BRA.S exit 
initGlobals: 
; Since NewHandle might trash *DCE in A1 ... 
MOVEA.L 20CSP2,A1 ; restore *DCE 
MOVE.L A@,dCtiStorage(Al)  ; save handle 
lockGlobals: 
-HLock 


; Mac C expects A4 to be pointer to global variables 
MOVEA .L (A0), A4 ; dereference handle 
; Since MOVE.W ®globalSize,D®@ causes an error ... 


DC.W $303C ; kludge instruction 
DC.W globalSize ; resolved by linker 
SUBA .W DØ, A4 ; add to globals ptr 


; Mac C expects *PB in DØ end *DCE in D1 
MOVE.L 16(SP), DØ ; get *PB from stack 
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MOVE.L 20(SP),D1 ; get *DCE 
MOVEA.L 36(SP), Ad ; get offset and... 
JSR (AQ) ; do Mac C routine 


; unlockGlobals 
; only Mac C open and control routines return here 
BSR. 


f indGlobals ; get handle 
~HUn lock 
restoreResult: 
MOVE.L D7,D9 ; restore result 
exit: 
MOVEM.L CSP2*,D4-D7? /A0/A 1/A4-A6 ; restore registers 
MOVE.W DØ, ioResultCAg) ; force result 
ADDQ.L 84 SP ; burn function ptr 


; Open and close return to the trap dispatcher 
; control goes to jIODone 
RTS 


disposeGlobals: 
; intercept Mac C close routine to dispose globals 
JSR close 
ADDQ.L 84 SP ; burn return address 
BSR.S f indGlobals ; get handle 
-DisposHendle 
MOVE.L Bü,dctlStorageCA1)  ; mark it empty 
BRA.S restoreResult 

f indGlobals: 


; Since HUnlock and DisposHandle trash result in DØ ... 
MOVE.L D0,D7 ; save result 

; Since Mac C routine might trash *DCE in A1 ... 
MOVEA.L 24(SP),A ; restore *DCE 
Em dCtlStorege(A12,AQ ; get handle 

RT 


else 

; Main routine if no global variables are needed 
MOVEM.L D4-D7/A®/A1/A4-A6, -CSP) ; Save registers 
; Mac C expects *pb in DØ and *dce in D1 


MOVE.L 16(SP ), DØ ; get *pb from stack 
MOVE.L 20(SP),D1 ; get *dce 

MOVEA.L 36CSP), Ad ; get offset and... 

JSR ` CAB) ; do Mac C routine 
MOVEM.L (SP )+,D4-D7/AB/A1/A4-A6 ; restore registers 
MOVE.W DØ, ioResult(Ag) ; force result 

ADDQ.L #4, SP ; burn function ptr 


; Open and close return to the trap dispatcher 
; control goes to jlIODone 
RTS 


endif 
Listing 3 
/* Filename: Clock.c originally compiled with Mac C 4.0 */ 
/* 
CLOCK version 22/26/86 


Copyright (021986 by Don Melton, all rights reserved. 


Clock is a desk accessory which opens a window displaying the 
current time in hours, minutes and seconds. It has a menu 
allowing the choice of displaying the time or dete, or an 
“About...” dialog. 

This is an example of how to create a desk accessory with 
Consulair Mac C without relying on the DeskMaker application. 
The source code is provided as a reference for Macintosh 
software developers. The clock desk accessory itself may be 
freely distributed as long as the copyright notice remains 
intact. 

-- Don Melton, CIS: 74166,1006 */ 
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MAC C COMPILER OPTIONS 
Setup A4 as the index to global variables and inhibit 
floating point. */ 


8Options R=4 Z 


8include <MacDefs.h> 
include «QuickDraw.h» 
*finclude <Font.h» 

* include «Window.h? 
*include <TextEdit.h» 
*include «Dialog.h? 

* include «Menu.h? 
*Sinclude <Events.h) 
include <Device.h> 
include «Packages.h»? 


"include «DeskAccessory.c? 


MODIFIED DEFINITIONS 

0SIO.h is not included because the OpParamType union 
Structure (as defined) does not provide access to the menu 
item. It is redefined here to include menuData and the event 
pointer. 

Note: Other alternate elements of the OpParamType union 
Structure are not defined here! 

The CntrlParem structure also must be def ined because 
0SIO.h is not included. However, it remains unaltered. */ 


union —_OP 
MAUS 


short menuID; 
Short menuItem; 
) menuData; 

Ptr event; 


) 
8define OpParamType union .. OP 
struct . CP 


struct —CP *ioLink; 
short ioType; 

short ioTrep; 

Ptr ioCmdAddr ; 
ProcPtr ioCompletion; 
short ioResult; 

char *ioNamePtr; 
short ioVRefNum; 
short ioRefNum; 
short CSCode; 

jenen iupe CSp; 


4 


"define CntrlPerem struct —_CP 


DEFINITIONS NOT IN MAC C HEADER FILES */ 
ate struct 


cher typeName[4]; 
) ResType; 


/* 
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CONSTANT DEFINITIONS */ 


define NIL Ø 
define FALSE 9 
“define TRUE 1 


"def ine FREE_BLOCK_SIZE @x 1000 
"def ine FRONT_WINDOW -1 


"define ABOUT.DLOG 1 
"def ine DISPLAY_ITEM 1 
#def ine TIME ITEM 1 
"define DATE. ITEM 2 
"def ine ABOUT. ITEM 4 
"def ine CLOCK MENU Ø 


"def ine TIME 8x020C 

"def ine WANT SECONDS 0x 100 
"def ine TIME. SELECTION 2 
"define DATE. SELECTION Ø 


SETUP DA HEADER AND GLUE ROUTINES 
The assembly language macro from DeskAccessory.c is 
invoked here. The order of parameters is: 


‘Name’ , ID, Flags, ServiceRate, EventMask, GlobalsRequest 


The DA event mask is set here to mouseDown, update and 
activate, but DAs will receive these events even if the mask 
is set to $0000. Since this is yet another undocumented 
"feature,^ it's best to be safe and use the correct mask 


beceuse future versions of the ROMs might behave differently. 
*/ 


asm 
DeskAccessory ‘Clock’, 12,$2400,$0010,$0142, NeedGlobals 
#endasm 


GLOBAL VARIABLES */ 


DialogPtr clockDialog; 
short ownedID; 

MenuHandle hClockMenu; 
long oldDateTime; 

Str255 oldDTString; 
Handle hDisplay; 

Rect displayRect; 

short textLeft, textBase; 
short clockFormat, clockSelection; 
short clockDirty; 

short oldWidth; 


OPEN CLOCK 

Since the FontDA/Mover renumbers all the IDs of any DA's 
resources whenever it moves a DA into another file, the new 
IDs must be calculated at runtime. The resource ID of a DRVR 
can be in the range 12-31, inclusive. Its owned resources are 
numbered differently. In this text, the global variable 
ownedID must contain the owned resources base ID number. The 
resource ID of the clock DRVR is initially 12, so its ownedID 
will be -16000. The ownedID can easily be derived from the 
dCtiRefNum field of the device control entry. [See the 
Assembly Leb in this issue for the formula for this. -Ed] 
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Setting the dCtlMenu equal to the ownedID is done before 
checking whether the DA is already open, because an open() 
call can come while the DA is still active. The Desk Manager 
resets dCtlMenu to whatever is in the DA header Cin this case 
zero) every time a DA is opened, so dCtlMenu must be 
reinitialized. 

It's possible to change the DA header at runtime to 
reflect the correct menu ID, but certain situations could 
actually cause the DRVR resource to be temporarily purged 
while the DA window was still open, thereby invalidating the 
patch. Besides, it's an ugly business to patch what is 
essentially a “code” resource. 

It's unecessary to recalculate the ownedID every time 
open() is called, but placing it outside the conditional saves 
code space. 

The MENU resource is made unpurgeable here because other 
events may cause heap compaction, purge the menu, and 
invalidate the menu handle. The menu is released from the heap 
during the DA closeC) function. 

All owned resources Cexcept possibly a MENU) including the 
DRVR itself should be preset as purgeable. Please note that 
this must be done with ResEdit, because RMaker does not allow 
this option at compilation. 

The windowKind field of the primary DA window should 
always be set equal to the dCtlRefNum field of the device 
control entry. The system needs a negative number in this 
field to recognize the window as belonging to a DA, and a 
specific number identifies a specific DA. 

The clock dialog is defined as invisible in the resource 
directive, Clock.r, because on exit of openO, the Desk 
Manager will always bring the DA window to the front of the 
desktop end meke it visible. The advantage to making the 
Window initially invisible is purely aesthetic. When 
GetNewDialog() is called, the Dialog Manager draws the window 
frame, reads the DITL resource into memory, makes a copy of 
it, and then begins drawing the items. If the dialog contains 
8 complex item list, waiting until the Desk Manager makes it 
visible will cause the dialog to be drawn faster. 

Setting the port to the clock dialog is done here because 
the TextMode of the grafPort is set to scrCopy. Getting and 
restoring the old port is also a good idea, however everything 
works properly if this is not done. 

To keep the DA window pointer away from other 
nonrelocatable blocks at the bottom of the heap, a 4K 
temporary space is allocated before the DA window pointer is 
created. Later it is disposed of during close(), or on an 
error of open(). This prevents possible heap fragmentation. An 
application can allocate more nonrelocatable blocks while a DA 
is active, and therefore can create a hole to small to 
reallocate when the DA is closed and its window pointer is 
removed from the heap. This DA also causes Pack6 to be loaded 
on to the heap. Pack6 is a locked resource which will remain 
on the heap until the heap is reinitialized. 

It is unnecessary for this function to draw the clock 
display or insert the clock menu because update and activate 
events are generated when a DA is first opened. */ 


short open(pb, dce) 
CntrliParem *pb; 
DCEntry *dce; 
GrafPtr oldPort; 
Ptr freeBlock; 
ResType dummyType; 
FontInfo theFontInfo; 


drvrID = 80xC000 - (32 * (1 + dce->dCtlRefNum)); 
dce-^dCtlMenu = ownedID; 


if CIdce— dCtlWindow) 
GetPortC&oldPort); 
if (ICfreeBlock = NewPtrCFREE. BLOCK. SIZE22) 
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return -1; 


if ClCclockDialog = 
"ial dial NewPtr(sizeof (DialogRecord)))) 


DisposPtr(freeBlock); 
Dum e 


clockDialog = GetNewDialogCownedID, clockDialog, 
FRONT. WINDOW); 
CCWindowPeek) clockDialog)-»windowKind = 
dce-? dCtlRef Num; 
dce-?dCtlWindow = (Ptr) clockDialog; 
SetPort((GrafPtr) clockDialog); 
TextModeCsrcCopy); 


hClockMenu = GetMenuCownedID); 
HNoPurgeChClockMenu); 


GetDItemCclockDialog, DISPLAY_ITEM, &dummyType, 
&hDisplay, &displayRect); 

GetFontInfoC&theFontInfo); 

textLeft = displayRect. left; 

textBase = displayRect.top + theFontInfo.ascent; 

clockFormat = WANT_SECONDS; 

clockSelection = TIME_SELECTION; 


DisposPtr(freeBlock); 
en 


return 8; 
) 


CLOSE CLOCK 

The MENU resource must be released from the heap here 
because an error will always occur during the next call to 
GetMenuC) in the openC) function (when the DA is selected 
again from the Apple menu) only during the operation of 
Finder versions 5.8 and above on the older 64K ROMs. As of 
this writing, no other application environments produce the 
error. Normally, the MENU resource would only need to be made 
purgeable. 

When GetMenu() is invoked it calls several other ROM 
routines including GetResource(), CountTypes(), 
CalcMenuSize(), GetItem(), MenuSelect() and LoadResource(). 
During the conditions mentioned above, on exit of GetItem(), a 
JSR (A0) instruction will produce an address error at a 
location above the 64K ROMs if the DA menu is on the heap. 
This is because the newer Finders jump directly in and out the 
128K ROMS at absolute locations, so they expect ROM code at 
specific memory addresses. 

If the DA menu is not on the heap when GetMenuC) is 
invoked during this environment, no error will occur. 

Apple Computer does not recommend using the newer Finders 
on the older ROMs. However, since many users have H020s hooked 
to their older Macs, they have to use the newer Finders. It's 
a good idea to prepare for these circumstances since there's 
no gain in code space, end the only operational difference is 
that the MENU resource must be reloaded every time the DA is 
opened. */ 


short close(pb, dce) 
CntrliPaeram *pb; 
coe *dce; 


deActivateCdce); 

Re leaseResourceChC lockMenu); 
DisposeDialog(clockDialog); 
dce-»dCtlWindow = NIL; 


return 0; 
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Contrary to popular practice, it's unnecessary to check the 
dCtlWindow field of the device control entry to determine 
whether the DA exists during control(). If a DA receives a 
call to control(), the DA had better exist! The only reason to 
check this field during control() is to determine whether the 
DA is the frontmost window. This is unnecessary in this DA. 

Setting the port to the clock dialog is done in 
drawDisplayC) rather than here, since drawDisplay() is the 
only routine drawing anything in the grafPort. */ 


short control(pb, dce) 
Cntr1Param *pb; 
a *dce; 


me (pb-? CSCode) 


case accEvent: 
doEventCCEventRecord *) pb->csp.event); 
break; 


case accMenu: 
doMenu(pb->csp.menuData.menultem, dce); 
break; 


default: 
drawDisplay(); 


return 6; 


MAIN EVENT LOOP */ 


doEvent( theEvent ) 
EventRecord *theEvent; 


2 ad (theEvent-» what) 


case updateEvt: 
updateClock(); 
break; 


case activateEvt: 
if CtheEvent->modifiers & activeF lag) 
ectivateC); 
else 
deActivateC); 
break; 


default: 
drawDisplay(); 


UPDATE CLOCK WINDOW 

Normally, if a dialog contains items such as buttons or 
text, a call to DrawDialog() is used between the calls to 
BeginUpdateC) end EndUpdate(). In the case this DA, a call to 
DrewDialog() is not only unnecessary, it will also cause an 
annoying flicker in the time/date display. This is because the 
empty static text item used to position the display will erase 
the dispaly again during the update. */ 


PEN ) 
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BeginUpdate(clockDialog); 
clockDirty = TRUE; 
drawDisplay(); 
EndUpdate(clockDialog); 


ACTIVATE CLOCK MENU 

Because older versions of the Font/DA Mover don't 
correctly reset the menuID of a MENU resource (not always the 
same as the resource ID!) when a DA is moved into another 
file, it must be patched here at runtime before the menu is 
inserted in the menubar. */ 


gi cad 


C*hClockMenu)->menuID = ownedID; 
InsertMenuChClockMenu, CLOCK. MENU); 
ee 


DEACTIVATE CLOCK MENU */ 
on 


DeleteMenuCownedID); 
DrawMenuBar C ); 


Choosing "About." in the "Clock" menu will invoke 
ModalDialog(). Since one of the first things Moda lDialog() 
does is call SystemTask(), the DA control routine can be 
called again. In the case of this DA, this problem of re- 
entrancy will not cause ModalDialog() to be invoked again 
because it can't be selected from the menu once the modal 
dialog is active. 

Remember that the code in DAHeader.asm which calls 
controlC), locks the global variables on the heap on entrance 
and then unlocks them on exit. The Desk Manager does this same 
thing to the DRVR code resource before and after the DA is 
called. 

To avoid the possibility of ModalDialog() causing heap 
compaction and moving either the DRVR code resource or the 
globals while unlocked, the device contro] entry of this DA is 
modified before ModalDialog() is invoked. If the DRVR was 
allowed to move during a call to ModalDialog(), the ROM 
routine could return to a memory address that no longer 
contained the DRVR code. 

First, to prevent control() from being called by 
SystemTask(), the dCtlEnable bit of the dCtlFlags field in the 
dce is cleared. This makes certain all global variables remain 
locked on the heap, because control() will not exit 
until the modal dialog routine is completed and the dCtlEnable 
bit is reset. 

Second, the dNeedLock bit of the dCtlFlags word is set to 
make certain the DRVR code resource remains locked on the 
heap. If the dNeedLock bit is set in the actual flags of the 
DA header, this step is unnecessary. However, using this 
technique makes presetting the dNeedLock bit unneccesary in 
most situations. 

Some programmers prefer to allow a DA to receive calls to 
controlC) while a modal dialog is active so the DA can still 
be performing certain tasks in the background. This is 
accomplished by using a complex technique which checks, clears 
or sets the dNeedLock bit on entrance to control() and then 
performs similar actions on exit. This techniques works OK if 
globals are handled differently than in DAHeader.asm. However, 
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it is much more confusing to constantly check the status of 
dNeedLock, than to use the simple techniques presented in this 
text, which still allow this DA to work while the modal dialog 
is active. */ 


doMenu(menuItem, dce) 
short menuItem; 
ri *dce; 


short theItem; 
DialogPtr aboutDialog; 


Switch Cmenul tem) 


case TIME_ITEM: 
if CclockSelection != TIME SELECTION) 
clockDirty =TRUE; 
clockFormat = WANT. SECONDS; 
clockSelection = TIME SELECTION; 
drawDisplay(); 
break; 


case DATE_ITEM: 
if CclockSelection != DATE_SELECTION) 
ClockDirty =TRUE; 
clockFormat = shortDate; 
clockSelection = DATE_SELECTION; 
drawDisplay(); 
break; 


case ABOUT_ITEM: 
dce-)dCtIFlags &= OxFBFF; /* clear dCtlEnable */ 
dce-?dCtlFlags °= 0x4000; /* set dNeedLock */ 
eboutDialog = GetNewDialogCABOUT_DLOG + 


owned ID, 
NIL, FRONT_WINDOW); 


o 
ModalDialog(doModal, &theItem); 
while 
CtheItem > oK); 


DisposeDialog(aboutDialog); 
dce->dCtiFlags “= 0x0400; /* set dCtlEnable */ 
dce-?dCtlFlags &= OxBFFF; /* clear dNeedLock */ 


) 
i a 


MODAL DIALOG FILTER FUNCTION 

Since the DA control routine is disabled before 
ModalDialog() is invoked, and SystemTask() can no longer call 
control1C) which then calls drawDisplay(); this function, 
called by ModalDialog(), draws the clock display. It must also 
check 
the modal dialog event record for a keypress character code 
equal to Return or Enter, and return a result to 
ModalDialog(). 

Since Mac C passes most parameters in registers, doModal() 
must be written in assembly language. 


The Lisa Pascal format for a dialog filter function is: 
PROCEDURE MyFilterCtheDialog: DialogPtr; VAR theEvent: 
EventRecord; VAR itemHit: INTEGER) : BOOLEAN; 


On entry the stack contains Cin descending order): 
space for boolean result (word) 
pointer to modal dialog (long) 
pointer to dialog event record (long) 
pointer to dialog item hit (long) 
return address (long) 
On exit: 
boolean result (word) 
return eddress (long) 
The “correct” method of addressing parameters passed to a 
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subroutine on the stack is to define them in a stack frame via 
a LINK An instruction on entrance and UNLK An on exit. 
However, the “correct” method takes more code space and is 
not especially any more legible than the implementation here. 
If Return or Enter characters have been generated from the 
keyboard, doModal() must set itemHit equal to 1 and return a 
result of TRUE. If not, it must return a result of FALSE so 
ModalDialog() will handle the event. 
Everything works correctly without saving any registers 
before calling drawDisplay(), but saving registers is always a 
good idea. */ 


doModal() 

( 

asm 
MOVE.L (SP)*,D0 ; save return address 
MOVEA.L (SP)*,AQ ; Save item hit ptr 
MOVEA.L CSP )+,A1 , Save event record ptr 
MOVE.L DB, (SP) ; restore return address 

; and trash dialog ptr 

MOVE .W (A12,D0 ; get evtNum 
CMPI.W 83,00 ; keyDwnEvt? 
BNE .S noKeyEvent 
MOVE .W 4CA12,D0 ; get evtMessage (low word) 


; check the character code, NOT the key code! 


CMPI.B #300 ; Enter character? 
BEQ.S setItemHit 
CMPI.B #13,D8 ; Return character? 
BNE.S noKeyEvent 
setItemHit: 
MOVE.W #1, CAB) ; first item is hit 
MOVE.W "$0100,4CSP) ; result is TRUE Chigh byte) 
RTS ; Skip drawDispaly() 
noKeyEvent : 
CLR. W 4CSP) ; result is FALSE 
MOVEM.L D3-D7/A3-A4,-(SP) ; save registers 


JSR drawDisplay 

MOVEM.L (SP)+,D3-D7/A3-A4 ; restore registers 

; RIS is inserted by the compiler after ")" 
Sendasm 


DRAW CLOCK DISPLAY 

Setting the port to the clock dialog is done here rather 
than in control(), because this function is also called by 
doModalC). However, everything works properly if the port is 
set only in control() and not here. Setting the port here is 
just a good idea. Getting and restoring the old port is also a 
good idea, however everything works properly if this is not 
done either. 

The current time is fetched from the low-memory system 
global "Time" ($020C) using C typecasting and indirection. 
Since the current time is not needed in many different places 
in this source, this technique is faster and tekes less code 
than writing an assembly language function. Also there's no 
equivalent in Mac C to the Lisa Pascal routine: 

PROCEDURE GetDateTimeCVAR secs: LONGINT); 

However, a function could be defined similar to this 
procedure but returning a long result, rather than having a 
veriable passed to it. For example: 


b getDateTimeC) 


asm 

MOVE.L $020C,00 ; Time 

; RIS is inserted by the compiler after ")" 
Üendasm 
) */ 
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draw) isp lay( ) 


GrafPtr oldPort; 
long newDateTime; 
Str255 newDTString; 
short newWidth; 


if CCclockDirty) || CCnewDateTime = *(Clong *) TIME)) != 
amis acini 


GetPort(&oldPort); 
SetPort((GrafPtr) clockDialog); 


oldDateTime = newDateTime; 

dTimeToStringCclockFormat, &newDTString, 
clockSelection); 

if CCclockDirty) || CCnewWidth = 
ee rine” < oldWidth)) 


oldWidth = newWidth; 
EreseRect(&displayRect); 
pen - FALSE; 


MoveToCtextLeft, textBase); 
DrewString(&newDTStr ing); 


prone cney 


CONVERT DATE OR TIME TO STRING 

This is a variation on two Lisa Pacal procedures contained 
in the international utilities package. There are no 
equivalents to these procedures in Mac C. Here the dateTime 
parameter is not used. Instead, the current time is fetched 
and placed on the stack, and a new parameter allows selection 
between date and time. 

The first parameter determines the format of the output. 
This is either the constants WANT. SECONDS or FALSE for time; 
or shortDate, longDate or medDate, for the date. 

WANT_SECONDS is defined as $0108 because it is a boolean 
TRUE, and therefore bit 1 of the high byte must be set. 
Actually any bit set in the high byte will work but setting 
bit 1 is the proper method. 

A pointer to the string which will contain the time or 
date characters is the second parameter. 

The third parameter is the selector for the Pack6 trap, 
either TIME_SELECTION or DATE_SELECTION. 


The Lisa Pascal format for the original two routines is: 
PROCEDURE IUDateString(dateTime: LONGINT; form: 
DateForm; VAR result: Str255); 
PROCEDURE IUTimeString(dateTime: LONGINT; 
wantSeconds: BOOLEAN; VAR result: Str255); */ 


dTimeToString(theFormat, theStr, theSelector) 
Short theFormat; 
Str255 *theStr; 
ri theSelector; 


"asm 
MOVE.L $020C,-(SP) ; Time 
MOVE .W DØ, -CSP) ; wantSeconds or dateForm 
MOVE .L D1,-CSP) ; theStr 
MOVE.W D2,-CSP) » routine selector 
DC .W $A9ED ; —Pack6 


; RTS is inserted by the compiler after ")" 
Ü'endasm 
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DA:Clock.rsrc 


TYPE DLOG 

," 16000 
Clock 
48 209 72 303 
Invisible GoAway 
4 


Ü 
- 16000 
,- 15999 


103 82 239 430 
Visible NoGoAway 
1 

ø 

-15999 


TYPE DITL 
,- 16000 
1 


StaticText Disabled 
4 6 20 88 


,- 15999 
5 


Button 
108 268 126 338 
OK 


StaticText Disabled 
10 10 26 338 
Clock 


StaticText Disabled 
34 18 58 338 
©1986 by Don Melton, all rights reserved. 


StaticText Disabled 
66 18 82 338 
A demonstration desk accessory designed for 


StaticText Disabled 
82 10 98 338 
MacTutor™ magazine and Consulair Corp. 


TYPE MENU 


> Filename: Clock. link 


/Globals -$0 
/Output Clock 

/Type 'DFIL' 'DMOV' 
/Resources 

Clock 

/Include Clock.rsrc 
/End 


The ABC's of C 
Starting with Hello World 


Welcome to How to C. This series will explore use of 
the C language on the Macintosh for those who don't know C 
and may have fairly limited experience programming the Mac. 
Put another way, if you often have the feeling that you don't 
know what's going on, this is a place to get your bearings. 

You'll find the following items useful to have around 
if you want to do more than program vicariously: 


e Using the Macintosh Toolbox with C by Takatsuka, 
Huxham, and Burnard (Sybex, 1986). This will serve as 
Our ‘text.’ It is currently the best available book on C on 
the Mac. We will generally follow their order of topics. 


* The C Programming Language by Kernighan and Ritchie 
(Prentice-Hall, 1978). If you are going to use C, you need 
this book. It is an amazingly clear and concise discussion 
of the language. 


e Inside Macintosh. Mainly because the first book does not 
cover everything. 


* A C development system. A number of compilers are 
available. We'll focus on Consulair's Mac C because the 
Using the Macintosh Toolbox book uses it, and because it 
uses MDS. If you're using a different compiler, don't 
worry. C is one of the more portable languages (between 
compilers and machines), and I'll try to point out differences 
when they appear. 


Ill also mention other useful sources of which I am 
aware. If you have any favorite books or articles, send me a 
note so we can share the information. 


Why Use C / Why Not Use C 


C was designed to be suitable for systems programming. 
As such, it is very flexible and allows programmers to do 
pretty much as they please. C is often characterized as a 
‘medium level' language. It offers the control mechanisms and 
data structures of a higher level language but at the same time 
allows access to the hardware and the ability to handle data in 
any way that seems suitable at the time. The compilers 
typically generate fairly fast, compact code. 

This flexibility is not without its costs, however. It is 
very easy to make a real mess of things (and generate 
incendiary devices on the Macintosh) by not getting the types 
of parameters correct. And some C notation can be downright 
cryptic. It is easy to make C code unreadable. 

In spite of the problems, I prefer C to Pascal. I could 
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usually do what I wanted with Pascal (depending on the 
compiler), but I knew I was cheating. And I could never be 
sure the technique would work the same way with a different 
compiler. 


Problems Using C on the Macintosh 


One problem with C vis-à-vis the Macintosh is that 
much of the C literature and many of the standard library 
functions assume you are using Unix or a Unix-like operating 
system. As you may have noticed, the Macintosh does not. 
This poses an additional set of problems for learning C on the 
Mac. The compiler makers follow two approaches. Some 
ignore Unix; others make the Mac look like it's running Unix. 


A second problem is that the Macintosh operating system 
assumes applications will be written in Pascal. This presents 
problems in at least two areas: strings and parameter passing. 


A C string is an array of bytes with a terminating zero (a 
byte of all zero bits, a binary zero, the null character, 
represented in C by V)). A Pascal string, as far as the 
Macintosh is concerned, is an array of bytes consisting of a 
leading byte containing the number of bytes in the string 
followed by the bytes of the string. Obviously sending a C 
string to a Toolbox function is not going to yield any sort of 
desired result. The compiler makers have solved this problem 
in two ways. Some compilers automatically convert the 
string when its passed; others provide a C function to do the 
conversion that you call before calling the Toolbox function 
(and another function to reconvert the string). Check your 
compiler's documentation to see what it does. 

The parameter passing problem involves a number of 
issues: where parameters are passed (stack or registers), the 
order in which they are passed, and how complex data types are 
passed. Most of the time you need not to be concerned with 
this at all; your compiler will do the necessary translations. 
In some cases (with some compilers) you must be aware of 
the difference. 


Getting Started 


The first program well do is the first program in 
Kernighan and Ritchie. This will force us to figure out how 
to set up our compiler, and use the editor, compiler, and 
linker. Now, at this point I should simply recount my 
experiences in getting "hello, world" to appear on my screen. 
Unhappily, I only recently received the compiler so I haven't 
done it yet. I also do not have two Macs so excuse me while I 
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figure this out. 

This month I've got Mac C™ from Consulair. It comes 
with three booklets of documentation, a letter from the author 
Bill Duvall, and some information sheets. One sheet 
describes the contents of the four disks. They include a public 
domain ram disk program written in Mac C called Ram Saart, 
so the first thing I did was to set up a ram disk. 

Using RamStart is a bit exciting. A help button is 
available, but if you don't click it fast enough, RamStart goes 
ahead and makes the ram disk. I don't remember exactly how I 
found that out: it is, of course, in the instructions, but you 
can't read the instructions unless you click help. Catch 22. 
Actually, the program is quite easy to use. Simply put what 
you want in the ram disk in the same folder with RamStart, 
and it creates the disk with those files in it. With Mac C, you 
may not have a ram disk larger than 280 K bytes (on a 512 K 
machine) or the compiler will run out of room. 

The Mac C package includes Edit, the four window 
mouse-driven program editor. Edit allows transferring directly 
to the compiler so you can invoke the compiler directly from 
Edit. 

hello, world 


Using Edit, I typed in the first program most people 
learning C try, a program to print "hello, world" on the 
Screen. 


#include "stdio.h" 


/ traditional first C program */ 
main() 


{ 
printf("hello, world"); 


That's the program. If you have never seen a C program 
before, there is a lot to examine even in this. 

The first line specifies an include file. This is a separate 
file that you wish to include as part of the compilation. These 
files typically contain constants, references to external 
functions, new symbols, and macros, but they can contain any 
code you wish to include. 

Here are some parts of the stdio.h that comes with Mac 


// stdio.h 


The double slash means comment to the end of the line. 
This is not standard. 


// Copyright 1984 Consulair Corporation. 
// All rights reserved 


// Aug 30, 1984 2:43 PM: New File 
// Standard UNIX IO library defs for MacC 


#define ERROR -1 


#define EOF -1 
#define NULL 0 
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#define MAXLINE 255 
#define FILE int 


The defines are instructions to the C preprocessor. These 
supply names to some oft-used values. In a program, you can 
use the name and the preprocessor will replace it with the 
value. By the way, standard C practice requires the "#" be in 
the first column. Mac C allows it anywhere on the line as 
long at is is preceded only by white space. 


// Standard Routines 


extern char putchar(); 
extern char fputc(); 
extern long putl(); 


extern int printf(...); 


There are references to external functions. External 
functions are functions defined in another file. For the 
compiler to work correctly, it needs to know the type of object 
returned, if any. Here we see that putchar returns a type char, 
putl returns a long, and printf returns an int. Most C 
compilers have a separate include file for each chapter in Inside 
Macintosh to provide the necessary definitions. 

To return to our program, the next line is: 


/* traditional first C program */ 


This is a comment. The "/* */" bracket comments. 


main() 


Every C program must have one and only one main 
function. It is where execution starts. Function names 
always have parentheses after them even if they have no 
parameters. 


{ 
printf("hello,world"); 
) 


The braces define a block of code that is handled as one 
line for program control purposes. They are similar to 
Pascal's begin-end. 

The only piece of code that does anything here is printf. 

It is used to write strings on the screen (the standard output 
device). It is not actually part of the language but is part of 
the standard library. The semicolon is a line terminator. 

A few comments are in order concerning other compilers. 
Mac C creates a TTY window for the standard C I/O functions. 
Other compilers may write directly to the desk top or require 
that you create a window for them. You will have to check 
the documentation. 

Next month we'll look at some more basic C concepts 
and start dealing with using C in the Macintosh environment. 
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C Workshop 
Palette Selection in Aztec C 


Making Palettes with the List Manager 

Apple's December 1985 Macintosh software supplement 
(which was shipped to “the rest of us” in March 1986) 
contains a variety of useful items, including the new List 
Manager Package. The List Manager provides a set of 
routines and data types for creating, maintaining and 
displaying lists and arrays of data elements. In its simplest 
form, you can use the List Manager to display a scrollable list 
of names, as in the Standard File Open dialog box. In other, 
more complex forms, you can use the List Manager to display 
arrays of arbitrary graphic images, as the displays of pictures 
and icons in the Resource Editor and the Chooser desk 
accessory. 

Apple implemented the List Manager as a package (like 
the Standard File, Disk Initialization and International Utilities 
packages) and placed it (as package 0) in the System resource 
file (version 3.1.1) which is included with the supplement. 
The supplement also contains an alpha draft of the new List 
Manager Package chapter of Inside Macintosh Volume IV. 

To show you what you can do with the List Manager, I 
used it implement a MacPaint-like palette of tools: 

In this example, the palette is represented as a 2 column 
by 10 row array (only 5 rows of which are visible at any one 
time), where each list element is a MacPaint tool icon. I 
instructed the List Manager to display the array and its scroll 


bar in a rectangle within its own window. Once the array is 
setup, the List Manager handles all mouse events, selections, 
and scrolling of the icons within the palette. 

The List Manager provides a variety of display 
alternatives. In the following two example, I arranged the 
palette as 10 column by 2 row array and as a 20 column by 1 
row array. 

In the following example, the palette is arranged as a 10 
column by 2 row array, where the whole palette is visible in 
its window, and so a scroll bar is not needed. 

The List Manager's Structure 

The List Manager is designed to maintain a set of data 
elements within a list, and to display the list in a rectangle 
within a window. The data elements themselves are displayed 
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the size of each data element may vary, the cells in which they 
are displayed must be the same size. When you create the list, 
you specify the horizontal and vertical size of a cell, as well as 
the number of rows and columns of cells the list is to contain. 
After the list is created, you can at any time add new rows or 


croire 
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columns to the list as well as delete existing rows and 
columns. The cells in a new list and in any new rows and 
columns are initially empty. 

Once you have created the list, or added rows or columns, 
you can set the values of the cells. The value of a cell is any 
arbitrary consecutive sequence of bytes of data, with the 
restriction that the total size of a list cannot exceed 32K bytes. 
Hence, a cell can store most anything - a text string, the bits 
of an icon, or the resource ID of a picture. 

At any given time, only a subset of the cells in the list 
may be visible in the list's rectangle within the window. The 
set of visible cells is determined by the size of a cell, the 
number of rows and columns in the list, and the current 
horizontal and vertical scrolling positions. 

The location of each cell in a list is specified by its row 
and column number. The top-left cell in the list is in column 
0 and row 0. The bottom-right cell in the list is in column c- 
1, row r-1, where the list contains c columns and r rows. The 
List Manager uses the Quickdraw Point data type to specify a 
cell's location. The horizontal coordinate specifies the cell's 
column, and the vertical coordinate specifies the cell's row. 

The List Manager calls a list definition procedure, which 
is normally stored as a resource in a resource file, to draw and 
hilite the data elements within a cell. Apple supplied a default 
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text-only procedure with the software supplement. For the 
palette, we'll have to write our own custom procedure to draw 
and hilite the palette's icons. 

The List Manager routine LNew creates a list, and returns 
a handle to the new list. 


ListHandle LNew(rView, dataBounds, cSize, theProc, 


Cell 0,r-1 Cell 1,r-1 NAE Cell c-1,r-1 


theWindow, drawlt, hasGrow, scrollHoriz, scrollVert) 


Rect *rView, *dataBounds; 

Point cSize; 

int theProc; 

WindowPtr theWindow; 

Boolean drawlt, hasGrow, scrollHoriz, scrollVert; 


The list will be displayed in the window specified by 
theWindow. RView specifies, in the local coordinates of 
theWindow, the rectangle in which the list will be drawn. 

The rectangle DataBounds specifies the initial dimensions 
of the list. Its top and left coordinates should both be 0. Its 
bottom coordinate specifies the number of rows in the list. Its 
right coordinate specifies the number of columns in the list. 
The point cSize specifies the size of each cell. Its horizontal 
coordinate specifies the width of a cell. Its vertical coordinate 
specifies the height of a cell. 

TheProc is the resource ID of the list definition procedure 
that will be used to draw and hilite the data elements within 
the cells. For the default text-only list, pass 0 and Apple's 
default list definition procedure will be used. 

If scrollHoriz is TRUE, the List Manager will place a 
horizontal scroll bar immediate below rView in the window 
and will enable all of the list's horizontal scrolling functions. 
Similarly, if scroll Vert is TRUE, the List Manager will place 
a vertical scroll bar immediately to the right of rView in the 
window and will enable all of the list's vertical scrolling 
functions. If hasGrow is TRUE, the scroll bars are sized to 
make room for a size box in the standard position. 

DrawIt specifies the initial value of the list's drawing 
mode. If the list's drawing mode is TRUE, all routines that 
affect the contents of cells, the number of rows and columns 
in the list, the size of the window, or which cells are visible 
within the rectangle, will cause the updated list to be drawn. 
If the list's drawing mode is FALSE, none of these operations 
will cause the updated list to be drawn, until the drawing mode 
is later set to TRUE, using the List Manager routine 
LDoDraw. 


void LDoDraw(drawlt, IHandle) 
Boolean drawlt; 
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ListHandle IHandle; 


LDoDraw sets the list's drawing mode to the state 
specified by drawlt. 

The ListHandle returned by LNew is defined as follows. 
For a more detailed description, refer to the List Manager 
Package chapter in the supplement. 


typedef Point Cell; 


iz d struct 


Rect rView; /* list's display rectangle */ 
GrefPtr port; /* list's grafPort */ 

Point indent; /* indent distance */ 

Point cellSize; /* cell size */ 

Rect visible; /* boundary of visible cells */ 


ControlHandle vScroll;  /* vertical scroll bar x/ 
ControlHandle hScroll;  /* horizontal scroll bar x/ 


char selFlags; /* selection flags */ 

Boolean lActive; /* TRUE if active */ 

char 1Reserved; /* reserved */ 

char listFlags; /* automatic scrolling flags */ 
long clikTime; /* time of last click */ 

Point clikLoc; /* position of last click */ 
Point mouseLoc; /* current mouse location */ 
Ptr 1ClikLoop; /* routine for LClick */ 

Cell lestClick; /* last cell clicked */ 

long refCon; /* list's reference value */ 
Handle listDefProc; /* list definition procedure */ 
Handle userHandle; /* additional storage */ 


Rect dataBounds; 
Handle cells; 


/* boundary of cells allocated */ 
/* cell data */ 

int maxIndex; /* used internally */ 

int cellArray(1]; /* offsets to data */ 

) ListRec, *ListPtr, **ListHandle; 


The List Manager provides a variety of cell selection 
algorithms, and defines the following predefined flags for the 
selFlags field of the list record shown on the top of the next 
page. 


"define lOnlyOne 128 /* set if only one selected cell */ 
#def ine lExtendDrag 64/* set for dragging without shift */ 
"define lNoDisjoint 32 /* set turns off multiple selects 
*/ 


define INoExtend 16 
x/ 


"def ine INoRect 8 
define lUseSense 4 
cell's 

Sdefine INONilHilite 2 


/* set to not extend shift selects 


/* set to not expand selections */ 
/* set for shift to use first 
sense */ 


/* set to not hilite empty cells */ 


For our purposes, only the lOnlyOne flag is useful, since 
only one icon may be selected from the palette at any time. 
Check the supplement for a description of the other flags. 

Once the list is created, the List Manager routine 
LSetCell may be called to set the value of a particular cell in 
the list. 


void LSetCell(datePtr, dataLen, theCell, lHendle) 
Ptr detePtr; 
int dataLen; 
Cell theCe11; 
ListHandle lHandle; 


LSetCell places the data pointed to by dataPtr and of 
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length dataLen into the cell specified by theCell in the list 
specified by IHandle. 

In addition to setting the value of a cell, the List Manager 
provides routines for selecting a cell as well as returning 
information about which cell (cells) is (are) currently selected. 


void LSetSelect(setIt, theCell, lHandle) 
Boolean setIt; 
Cell theCe11; 
ListHandle lHandle; 


If setIt is TRUE, LSetSelect selects the cell specified by 
theCell in the list specified by lHandle. If setIt is FALSE, 
LSetSelect deselects the cell. 


Boolean LGetSelect(next, theCell, lHendle) 
Boolean next; 
Cell *theCe11; 
ListHandle lHendle; 


If next is FALSE, LGetSelect returns TRUE if the 
specified cell is selected, or FALSE if not. If next is TRUE, 
LGetSelect returns in theCell the cell coordinates of the next 
selected cell after theCell in row major order, and returns 
TRUE. If there are no selected cells after theCell, FALSE is 
returned. 

The List Manager provides several routines that should be 
called in response to certain events. 


void LActivateCact, lHendle) 
Boolean act; 
ListHendle lHandle; 


You should call LActivate to activate or deactivate the 
list specified by [Handle in response to an activate event in the 
window containing the list. Act should be set to TRUE to 
activate the list, and FALSE to deactivate it. 


void LUpdateCtheRgn, lHandle) 
RgnHendle theRgn; 
ListHandle lHendle; 


You should call LUpdate in response to an update event. 
TheRgn should be set to the visRgn of the lists window. 
LUpdate redraws the visible cells and the scroll bars, if 
necessary. 


Boolean LClick(pt, modifiers, lHendle) 
Point pt; 
int modifiers; 
ListHendle lHendle; 


Call LClick in response to a mouse-down event in the 
list's rectangle or its scroll bars. Pt is the mouse location in 
local coordinates. Modifiers is the modifiers word from the 
event record. The result is TRUE if a double-click occurred. 

LClick keeps control until the mouse is released. If the 
pointer is in the lists rectangle, cells are selected 
appropriately. If the pointer was in the rectangle, but is 
dragged outside, the list is auto-scrolled. If the pointer was in 
a scroll bar, its control definition procedure is called to track 
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the mouse, and the list is scrolled appropriately. 

In addition to the 8 routines described above, the List 
Manager provides an additional 18 routines. Check the 
supplement for their description. 

Implementing the Palette 

With help of the List Manager, implementing the palette 
is relatively straightforward. First LNew is called to create a 2 
column by 10 row list. Then LSetCell is called to set the 
value of each cell to the 128 bytes of the appropriate icon. 
The icons themselves are stores as ICON resources in the 
application's resource file. 

Once the palette is created, the routines LActivate, 
LUpdate, and LClick are called in response to the appropriate 
events. 

The routine IconListDef is our custom list definition 
procedure that draws and hilites the icons in their respective 
cells. A list definition procedure must have the following 
parameters: 


void ListDefProcClMessege, lSelect, lRect, 1Cell, lData0ffset, 


lDetaLen, lHaendle) 
int lMessage; 
Boolean lSelect; 
Rect *lRect; 
Cell 1Cell; 
int lDateOffset, lDataLen; 
ListHandle lHandle; 


The IMessage parameter identifies the operation to be 
performed. It has one of the following values: 


"define lInitMsg 8 /* do any additional list initialization 
x 


/ 
define lDrewMsg 1 /* drew and optionally hilite the cell 
x 


"define lHiliteMsg 2 
#def ine 1CloseMsg 3 


zi 


/* invert the cell's hilite state */ 
/* take any additional disposal action 


LSelect is TRUE if the cell should be selected. LRect is 
the rectangle in which the cell should be drawn or hilited. 
ICell identifies the cell's column and row. LDataLen is the 
length in bytes of the cell's data. LDataOffset is the offset 
into the list's cell data of the cell to be drawn or hilited. 
IHandle is a handle to the list record. 

Our routine IconListDef ignores the lInitMsg and 
ICloseMsg, since no private storage is needed. 

In response to an IDrawMsg, IconListDef uses the 
Quickdraw CopyBits routine to copy the bits of the icon from 
the list's cell data into the argument rectangle IRect. Then, if 
ISelect is TRUE, InvertRect is called to hilite the icon. 

In response to an 1HiliteMsg, IconListDef simply calls 
InvertRect to invert the hilite state of the icon. 

Since LNew expects that the list definition procedure is 
stored as an LDEF resource in a resource file, I defined a 6 
byte LDEF resource that contains the single instruction 


JMP $00000000 


Then, before calling LNew, the following code is used to 
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modify the destination of the JMP instruction to the routine 


IconListDef: 


theLDEF = GetResourceC'LDEF', LDEF); 
*Clong *) (*theLDEF + 2) = Clong) &IconListDef ; 


This scheme is reasonable since the LDEF resource is 
non-purgeable and the IconListDef routine is in a non- 


relocatable CODE resource. 


The application itself was written for the Manx Aztex C 


compiler. 


/* 
* Palette List Application 
*/ 


#include <event.h) 
#include «inits.h» 
#include «list.h» 
"include <(memory.h? 
8include «menu.h»? 
include <packages.h) 
"include «quickdraw.h» 
*include «resource.h» 
include «segment.h» 
®include «toolutil.h» 
include «window.h» 


"define MENUBAR 256 
"define WINDOW 256 
"define ICON 256 
"define LDEF 256 
"def ine GRABBER 256 


"define WIDTH 26 
"define HEIGHT 22 
#define ROWS 10 

"define COLUMNS 2 


"define POINTCthePt) *Clong *)(&thePt) 
WindowPtr palette; 
maint) 


MacInit(); 

MenuInitC); 

PaeleInit(); 

for (;;) 
EventDoOneC); 


iss 


InitGref C&thePort); 
InitFonts(); 

InitWindows(); 

InitMenusC); 

TEInitC); 

InitDialogsC01); 
FlushEventsCeveryEvent, 9); 
eee 


TEAM 


Se tMenuBar (Ge tNewMBar CMENUBAR2); 
ai a 


pascal void IconListDef( Message, lSelect, lRect, Cell, 
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WData0ffset, IDataLen, lHandle) 
int lMessage; 
int lSelect; 
Rect *Rect: 
long 1Cell; 
int lDateOffset; 
int 1DataLen; 
oe lHandle; 


char tag; 
BitMep iconBits; 


BlockMoveClRect, &iconBits. bounds, (long) sizeof(Rect)); 
dba (Message) 


case lInitMsg: 
break; 


case lDrawMsg: 
if sed 


tag = *(char *) C*lHandle)- cells; 

HLockCC*TlHendle)-?ce11s); 

iconBits.baseAddr - *(*]Handle)-cells * 
IData0ffset; 

iconBits. rowBytes = 4; 

CopyBits(&iconBits, &thePort->portBits, 
lRect, lRect, srcCopy, 91); 

*(char *) (*1Handle)- cells = tag; 


else 
EraseRect(1Rect); 

if (I*(char *) &1Select) 
break; 


case lHiliteMsg: 
iconBits.bounds .right--; 


Inver tRect(&iconBits. bounds); 


break; 
case lCloseMsg: 
break; 
) 
IBN 


Handle theLDEF; 
Rect theView; 

Rect theBounds; 

int scroll; 

Point theSize; 
ListHandle thel ist; 
Cell theCe11; 

int id; 

Handle theIcon; 


palette = GetNewWindow(WINDOW, 21, -11); 


theLDEF = GetResource('LDEF ', LDEF); 
*Clong *) (*theLDEF + 2) = (long) &IconL istDef ; 


SetRect(&theBounds, 9, Ø, COLUMNS, ROWS); 

BlockMove(&palette->portRect, &theView, (long) 
sizeof (Rect)); 

if (scroll = CtheView. bottom - theView.top) / HEIGHT « 
ROWS) 

theView.right -= 15; 

SetPt(&theSize, WIDTH, HEIGHT); 

theList = LNew(&theView, & theBounds, POINTCtheSize), 
LDEF , palette, FALSE, FALSE, FALSE, scroll ? 
TRUE : FALSE); 

SetWRef Con(palette, theL ist); 

(*theList)- -)selFlags = 10n1yOne; 
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iconBits.bounds.bottom-- 


for e = Ø; id < COLUMNS * ROWS; id**) 


SetPtC(&theCe11, id $ COLUMNS, id / COLUMNS); 
HLockCtheIcon = GetIconCid + ICON)); 
LSetCellC*theIcon, 128, POINTCtheCel1), theList); 
o eens 


SetPtC&theCell, 2, 0); 
LSetSelectCTRUE, POINTCtheCel1), theList); 


LDoDrawCTRUE, theList); 
(renner 


EventDoOne( ) 


EventRecord theEvent; 
WindowPtr theWindow; 


if CGetNextEventCeveryEvent, &theEvent)) 
em CtheEvent . what) 


case mouseDown: 
switch CFindWindowCPOINTCtheEvent . where), 
&theWindow)) 


case inMenuBar : 
if (MenuSelectCPOINTCtheEvent . where)2) 
ExitToShel1(); 
break; 


case inContent: 
if Pid & optionKey) 


SetCursor(*GetCursor CORABBER22; 

LActivateCFALSE, GetWRefCon(palette)); 

DragWindowCpalette, POINTCtheEvent .where?, 
&screenBits.bounds); 

LActivateCTRUE, GetWRefCon(palette)); 

mn RER 


else 


SetPort(palette); 

GlobalToLocalC&theEvent . where); 
LClickCPOINTCtheEvent . where?, 

LEES GetWRef ConCpalette2); 


em 
break; 


case updateEvt: 
BeginUpdate(palette); 
LUpdate(palette-»visRgn, GetWRefCon(palette)); 
EndUpdate(palette); 

break; 


cese activateEvt: 

LActivateCtheEvent .modif iers & activeFlag ? TRUE : 
FALSE, GetWRef ConCpalette)); 

PU 


) 
) 


A Few Resources 

The following file is a list of the resources used by the Palette 
application. The file Palette.app contains the linked 
application. The file Palette.icon contains the tool icons and 
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application cursors. The file List.pack contains the List 
Manager package. (You don't need to include this file if the 
List Manager package resides in your System file, ie System 
File 3.1.1, the latest release.) 


x 
* Palette List Resources 
x 


Palette :Palette 
APPLPALE 


Include Palette:Palette.app 
Include Palette:Palette. icon 
Include Palette:List.pack 


Type MBAR 


= GNRL 
,256 (4) 
I 


1 
.I 
256 
Type MENU 
,256 (4) 
File 
Quit 
Type WIND 
,256 (4) 
Untitled 
* bounds for 5 rows with scroll bar: 29 15 139 82 
* bounds for 18 rows without scroll bar: 29 15 249 67 
29 15 139 82 
Invisible NoGoAway 


g 
Type LDEF = GNRL 
56 (4) 


4 


4EF9 0000 0000 


A List Manager Interface 

The following file is the List Manager interface for Manx 
Aztec C. Each of the routine nubs first pops a return address 
off the stack, pushes the appropriate package routine selector 
word, pushes the return address back onto the stack, and then 
invokes the  PackO trap. The auto-pop bit in the , PackO trap 
Word is set so that control returns to the invoking routine. 


Manx Axtec C interface to the List Manager 


lActivate equ ð 

1AddColumn equ lActivate+4 
1AddRow equ lAddColumn*4 
lAddToCe11 equ lAddRow*4 
lAutoScrol] equ lAddToCe11*4 
lCellSize equ lAutoScrol1*4 
1Click equ 1CellSize*4 
1CirCell equ ]Click*4 
1De1Column equ 1CirCel1+4 
1De1Row equ 1De1Column+4 
Dispose equ 1DelRow*4 
1DoDraw equ ]Dispose*4 
1Draw equ ]DoDraw*4 
]Find equ 1Draw+4 
1GetCel] equ ]F ind*4 
lGetSelect equ 1GetCel1+4 
]LestClick equ lGetSelect*4 
1New equ lLestClick*4 
lNextCell. equ lNew*4 
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]Rect 
1Scro11 
]Search 
1SetCe11 
lSetSelect 
Size 
lUpdate 


public 


-ListCall: 
move. | 
move .w 
move. | 
dc.w 


public 
LNew_: 
moveq 
bra 


public 
LDispose_: 

moveq 

bra 


public 
LAddColu_: 

moveq 

bra 


public 
LAddRow. : 

moveq 

bra 


public 
LDe1Colu_: 

noveq 

bra 


public 
LDelRow_: 

moveq 

bra 


public 
LAddToCe_: 

moveq 

bra 


public 
LCIrCell_: 

noveq 

bra 


public 
LGetCe11. : 

moveq 

bre 


public 
LSetCe11.: 

moveq 

bre 


public 
LCellSiz..: 

moveq 

bra 


public 
LGetSele_: 

moveq 

bra 


equ 
equ 
equ 
equ 
equ 
equ 


1NextCe11+4 
TRect+4 
1Scro11+4 
lSearch*4 
1SetCel1+4 
]SetSelect*4 


equ lSize*4 
begin 
CAT)+, Ad 

DO ,-CAT) 

A0, -CAT) 

$ade7 

LNew_ 


#1New, DØ 
ListCall 


LDispose_ 


®1Dispose, DO 
-ListCa11 


LAddColu_ 


®]AddColumn, DØ 
-ListCall 


LAddRow.. 


#1AddRow DØ 
ListCal] 


LDelColu_ 


#1De1Column, DØ 
ListCall 


LDelRow.. 


#1De Row, DØ 
-ListCall 


LAddToCe_ 


* |AddToCe11,D0 
-ListCall 


LCirCell_ 


81ClrCe11,00 
-ListCall 


LGetCe1l.. 


"1GetCe11,D0 
-ListCa11 


LSetCe11.. 


81SetCe11,D9 
-ListCa11 


LCellSiz. 


#1Cel1Size, Dd 
-ListCall 


LGetSele_ 


®]GetSelect, DØ 
-ListCall 


rd 


; push routine selector 
; push return address 


4 
* 
4 


pop return address 


pack®, with auto-pop 
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public 
LSetSele_: 

moveq 

bra 


public 
LClick_: 

moveq 

bra 


public 
LLastCli_: 

moveq 

bra 


public 
LFind_: 

moveq 

bra 


public 
LNextCel_: 

moveq 

bra 


public 
LRect_: 

moveq 

bra 


public 
LSearch_: 

moveq 

bra 


public 
LSize_: 

noveq 

bra 


public 
LDraw_: 

moveq 

bra 


public 
LDoDraw_: 

moveq 

bra 


public 
LScrol1_: 

moveq 

bra 


public 
LAutoScr. : 

moveq 

bra 


public 
LUpdate. : 

moveq 

bra 


public 
LActivat_: 

moveq 

bra 


end 


LSetSele_ 


"]SetSelect,D0 
-ListCall 


LClick_ 


#1Click, DO 
ListCall 


LLastCli_ 


8S1LastClick,D0 
_ListCal] 


LFind_ 


#1F ind, Dd 
ListCal] 


LNextCel_ 


®1NextCe11, Dd 
-ListCall 


LRect_ 


#IRect,DØ 
-ListCall 


LSearch_ 


®1Search, D0 
-ListCall 


LSize_ 


"1Size,D0 
-ListCall 


LDraw_ 


*]Draw, Dd 
-ListCall 


LDoDraw.. 


81DoDraw,DO 
-ListCall 


LScroll.. 


t'19cro11,D0 
ListCall 


LAutoScr.. 


"8lAutoScro11,D0 


-ListCall 
LUpdate_ 


#1Update,DØ 
-ListCal]l 


LActivat— 


*lActivate, DO 
ListCall 


The ABC's of C 


Structures and the Event Loop 


Beginning this month, we will start following the 
chapters in the Using the Macintosh Toolbox with C book. 
This means we're will be learning about C and the Macintosh 
at the same time. While this is probably not the optimum 
way to learn a language, it means we can explore features of 
the language and the Mac and have a lot of time to play around 
and make mistakes. As you will see from this month's effort, 
I am not afraid to make lots of mistakes. 


We are going to start right away with a program that 
demonstrates a bit about the Event Manager. Events are a 
critical component to the way Macintosh software functions. 
They are not visible like windows or pull-down menus, but 
they occupy a central location in most applications 
nonetheless. 


From the point of view of the Event Manager, Macintosh 
program spend most of their time sitting around waiting for 
events. Events can come from the keyboard, the mouse, disk 
drives, the Window Manager, et cetera, as well as your 
application. 


Structures 


For the moment, we won't worry too much about how 
the Event Manager gives you an event. Instead, we'll use the 
event to examine an important C data construct called a 
structure. A structure is a collection of variables usually of 
different types organized under a single name (loosely 
paraphrased from K&R). An event from a software point of 
view is a structure: 


struct ER 


(short what; /* kind of event */ 
long message; /* event info */ 

long when; f* time of event */ 
Point where; /* mouse location */ 


short modifiers; ^ /* other info */ 


) 


The variables collected together in the structure are 
members. 


A structure declaration (as we have above) does not 
reserve any memory. We still need to define a variable: 


struct ER event; 


defines the variable, event, to be of type ER. Now, when 
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the Event Manager gives us an event, we can examine its 
members to determine what to do. To access the members of 
a structure, use a period between the variable name and the 
member name: 


event.what 


At this point, let us look more closely at the where 
member. It is obviously not one of the standard C types. It 
is in fact another structure: 


struct pt 
(short v; /* vertical location */ 
short h; /* horizontal location */ 
}; 


So structures may be nested in other structures (you can 
also have arrays of structures). 


You noticed that I defined the structure "pt" not "Point." 
When we defined the event variable, above, we wrote struct 
ER event. C requires that you let it know each time you 
are dealing with a structure. Writing struct all over your 
programs can be a drag as well as making them less readable. 
C has a couple of ways to deal with this problem. One is the 
typedef, which is way of providing a new name for a type. 
Point then becomes: 


typdef struct pt Point; 


The other technique is to use the preprocessor define 
feature: 


#define EventRecord struct ER 


Both of these techniques will increase the clarity of our 
code. The typedef is preferred because it is actually a part of 
the compiler and can deal with certain situations that can 
confuse the lexical substitutions of the preprocessor. Some 
micro C compilers do not include typedefs, however. 


Now that we have defined the EventRecord, we can get an 
event from the Event Manager and see what to do with it. 


Switch Statement 


The first thing to do is decide what kind of event it is 
(from the what member), and then take appropriate action. 
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The clearest way to do this in C is with the switch or case 
statement (C calls it switch, but many C programmers call it 
a case statement). The switch is a multi-way branch: 


Switch (integer expression) 


case constant1 : code; 


break; 
case constant2 : more code; 

break; 
default : code; 

break; 
} 


The break statements are needed to keep the code from 
falling through the cases. Without the break, if the 
expression matched constant2, it would continue execution 
with the default code. The break forces execution to 
continue after the closing }. The default is chosen if 
none of the other cases match. By the way, you can have 
several constants that match one section of code. Each is 
preceded by case and followed by acolon. In effect, they fall 
through to the first code to execute. 


A Program that Demonstrates the Event Manager 


/* Event Manager Demonstrator */ 


#include ^ "stdio.h" 
#include — "MacCDefs.h" 
#include ^ "Events.h" 
main() /* This may look silly, butin — */ 
/* subsequent programs we will have */ 
/* initialization routines up here. */ 
mainloop(); 
mainloop() 
EventRecord event; 
while (True) 


if (GetNextEvent(everyEvent,&event)) 
Switch (event.what) 


case mouseDown: printf(^nmouse down"); 


break; 

case mouseUp: printf(^nmouse up"); 
break; 

case keyDown: printf("\nkey down"); 
break; 

case keyUp: printf("\nkey up"); 
break; 

case autoKey: printf("\nautokey”); 
return; 
break; 

case updateEvt: break; 

case diskEvt: printf(^ndisk event"); 
break; 

case activateEvt: break; 
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case networkEvt: break; 
case driverEvt : break; 
case nullEvent: break; 


} 
} 


GetNextEvent() is the Event Manager routine that returns 
the next event record each time its called. If there are no 
events to return, it returns the Null Event. 

All the constants (nullEvent, mouseUp, et cetera) and the 
EventRecord structure are defined in Events.h. I recommend 
you take a look at the copy that comes with your compiler. 

The program exits on an autokey event. To stop the 
program, simply hold a key down. 

The first parameter to GetNextEvent() is the event mask. 
With it, you can select the events to which you wish to 
respond. It's a bit mapped mask; you can combine events by 
adding the constants defined in events.h together. EveryEvent 
is all 1 bits (-1 decimal). 

You will probably not see the key up event. It is 
generated when you release a key. It took me awhile to find 
out why I wasn't seeing it, but I finally took a look at Inside 
Macintosh. 

There is a second event mask that controls which events 
get entered into the event queue. Since GetNextEvent() gets 
events from the queue, if an event is masked Out, 
GetNextEvent() will never be able to return it This event 
mask is initialized to: 


everyEvent - keyUpMask 


so it will not even post key up events. There is a 
function, SetEventMask(), that will set this, but it is 
apparently not included in Mac C. 


Some Things to do 


This program is very brief, but you can easily add a few 
lines to get a better feel of how the Event Manager works and 
how to use some C functions. Try examining the where field 
on each event. Remember this is a Point structure. The 
message and modifier fields provide essential information for 
some events, especially key events. Print these out as well. 

There are a number of other functions in the Event 
Manager. They allow reading the mouse, keyboard, and time 
without waiting for an event. There is also a function to read 
the event queue that leaves the event in the queue. 


We will not do any more with the Event Manager at this 
time, but we will use it in probably every program we write. 


Finally, if anyone is reading along, I would appreciate 
hearing from you. Let me know if this is useful or if you 
have an idea for a short program we can do in the column. 


Programmer's Forum 
Philosophy of DA Programming 


We are grateful to have this article from David Dunham, 
best known for his desk accessory DiskInfo, now in version 
1.41. In this article, he shares some of his experiences in 
writing a first class DA. -Ed. 

Introduction 

Desk accessories (DAs) are in many ways one of the best 
design features of the Macintosh. Not only did Apple provide 
a clean way to handle them (unlike theincompatibilities 
between DAs under MSDOS), they're currently the only way 
the average user is going to multitask. 

In my opinion, desk accessories are really no different 
from applications. Examples of desk accessories which do the 
job of applications are MockWrite, ClickOn Worksheet, and 
Acta. One developer wondered why everything on the Mac 
couldn’t be a DA. There’s really no reason, except that the 
Mac architecture implements them as drivers, and the unit 
table is limited to 32 entries. So we're stuck. 

Although in one sense writing a desk accessory should be 
no different than writing an application (Acta started out life as 
an application, and was easy to convert), there are some 
differences, mainly because desk accessories are the guests of 
an application. I'll discuss implementing DAs at a fairly 
abstract level. Plenty of detailed articles on desk accessories 
have already been published. See the Oct 85, Nov 85, Jan 86, 
Feb 86, Mar 86, or Apr 86 issues of MacTutor or the Oct 85 
issue of MacUser for complete listings. I'll talk about what 
I've learned writing the DAs DiskInfo, FileInfo, and Acta. 

Edit Menu 

An accessory that manipulates data almost certainly needs 
to support the Edit menu. But if you use the Edit menu, 
you're confronted with the fact that many applications don't 
include the keyboard equivalents to the standard commands. In 
fact, ThinkTank doesn't even provide an Undo menu item at 
all! This means that you'll have to handle the standard 
equivalents (e.g. Command-Z for Undo). 


EventRecord *ep; 


/* This code is necessary because */ 
/* MenuKey() won't check for Edit menu */ 


cese keyDown: 
cese eutoKey: 
c = (word)Cep-»message & 255); 
if Cep-»modifiers & cmdKey) ( 
item*/ 


/* Mask for low byte */ 
/* Pretzel key , menu 


switch Cc) ( 
cese 'Z': 
case 'z': 
/* You may want to check for option-equivalents, too */ 

undo. cmd( 2; 
break; 

case 'X': 

case 'x': 
cut_cmd(); 
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break; 


Note that this causes a localizing problem, since non- 
English systems may use different keyboard equivalents (the 
leftmost four keys on the bottom row are still used). 

If at all appropriate, include Undo! I don't consider 
anything a true Mac program without it. And it impresses 
people. When Guy Kawasaki of Apple first saw Acta, he 
exclaimed, *You have Undo in a desk accessory?!" Having 
Undo is impressive because desk accessories are often 
considered poor cousins of applications. But ClickOn 
Worksheet provides more features than Multiplan, and Acta's 
application equivalent lacks Undo. 

Goodbye Kisses 

Any intelligent application asks the user to save his work 
before quitting. Since desk accessories don't have access to 
the File menu, it isn't quite as easy to implement this feature. 
Luckily, Apple provided the goodbye kiss, a special call to 
your accessory before the heap is reinitialized. This is your 
way of knowing that the user quit the application, and is the 
time to remind him about unsaved changes. Users tend to get 
unhappy if they lose data, even if it's because they didn't quit 
in the "proper" way. 

When I was trying to implement this feature, I couldn't 
find a single DA that had it! (I've since learned that ClickOn 
Worksheet [which by now you can tell I admire greatly] does 
field goodbye kisses.) In fact, since I couldn't get it to work, 
and since I couldn't determine that it worked anywhere else, I 
was convinced that it didn't work at all. It does. You do need 
to return via JIODone, which may be difficult in a high-level 
language. Mike Schuster's article in the April MacTutor had 
some clever glue to handle this. I did it with inline code: 


/* Pbp is a global pointer to the parameter block */ 

/* restore() restores registers */ 

if (Pbp- u.cp.csCode < Ø) ( /* Goodbye kiss */ 
close-windowC); /* Close it NOW */ 


restore(); /* Since above affects 
A0/A1 */ 
close(); /* Exactly same as close box */ 
asm 
nove.1 Dp, A1 ; restore DCE pointer 
move .w #9 DO ; Return code 
movem.] (SP)+,.registers  ; normally done in a return 
unik A6 
move.1 JI0Done, -CSP) ; Goto IODone 
rts 
Sendasm 


I found that I had to close the DA window first, 
presumably since I was putting up an SFPutFile() dialog and 
thus getting reentrant calls. However, at the time of a 
goodbye kiss, your window may be gone already; programs 
like MacWrite close all windows before quitting (but don't 
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close the desk accessory associated with a window.. .). Here's 
a routine to close your window only if it's still there; I found 
this attributed to Mike Schuster: 


[PPPOODOCODODODOOEOROPERROOOHOOUOOOOEDOOCOOODO)OOOOOODERE / 


/* 


x/ 
/* CLOSE_WINDOW - Close our window, if it's there. */ 
/* Note: Dp is the global DCE pointer */ 
/* 

x 


POODOCOCOOODOOODOODODOOODODODOEOOOIOOE OOEOOOOEOGOE / 


close_window() ( 
WindowPeek w; 


/* Make sure window's still there before getting rid of it. 
*/ 

/* It may be gone, because applications like MacWrite */ 

/* close all open windows without regard to */ 

/* what they are. */ 


/* Start at beginning of window list */ 
w = FrontWindow(); 
/* Look for our window */ 
while Cw && w != Dp->dCtlWindow) 
w = w-nextWindow; 
/* If we found it, get rid of it x/ 
if Cw) 
CloseWindow(w); 
Dp-»dCtlWindow = Ø; 


Files 

Your DA can create, delete, and rename files, even from 
the Finder. The newer Finders handle these changes properly. 
All you have to do is call FlushVol() after making any 
changes. This signals the Finder to update the desktop (and 
it’s something you should do anyway after altering a disk). 

There are a few things that you shouldn't do from the 
Finder. These include changing the FinderInfo of a file, 
including its type and creator. Apparently the Finder keeps 
those in memory, and doesn't update its copy if a DA changes 
them. If it then writes desktop information before launching 
an application, it overwrites what the DA did with its original 
copy. 

If your DA uses a resource file to store information (like 
the Scrapbook File), you should open it on bootDrive (the 
global at $210). Despite its name, this is the vRefNum or 
WDRefNum where the Finder is located. In other words, the 
System Folder (usually). 

If you want your DA’s files to have distinctive icons, 
you'll have to figure out a way to get the bundle into the 
Desktop file. It's best to put the bundle in a support program, 
such as an installer or configurer. This should be less 
confusing than having the user copy a special file to a disk, 
then delete it. 

Menus 

If you're going to use more than one menu, they won't 
fit. You'll have to change the entire menu bar in order to 
guarantee enough space. 

In fact, the easiest way for the menu bar to run out of 
room is to use DAs that consist of just a menu. Several of 
these can swamp an application with many menus. So be 
sure thé world needs another menu-only DA before you write 
one. 
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The big problem with menus is that your DA may have 
enough functions to require more than one. At least the 
current System has scrolling menus...but if there are more 
than 19 items, your user might not realize there are any down 
below (this is where Apple really screwed up...there was 
another implementation of scrolling menus that, while buggy, 
gave a visual indication of extra items). 

Because a few applications don't handle highlighting DA 
menus properly, you should call HiliteMenu(0) after handling 
an accMenu call. 

Zooming 

A nice feature to provide is the capability for the user to 
expand a window to its maximum size. The fairly common 
practice of double-clicking the title bar won’t work with a DA, 
because the DA never sees title bar events (the Desk Manager 
handles things like TrackGoAway( and DragWindow(). With 
the new ROMs, Apple came up with a standard way of 
enlarging a window to its maximum size: the zoom box. 

Luckily, a mouseDown in the zoom box can be detected bya 

DA. It’s not that simple though, because FindWindow(, 
which applications can use to determine the logical position of 
a click, always returns inSysWindow. However, the 
mouseDown will have a position outside the portRect of your 
window, so it's easy to identify. 

You could try to keep track of the zoom state yourself, 
but this won't work, because the window manager recognizes 
when the user drags and resizes a window into its zoomed size. 
The correct method is to call the WDEF and let it tell you 
where the hit is. 

By the way, you don’t need to worry about whether 
you're running on the new ROMs or not, because the WDEF 
won't even draw the zoom box under the 64K ROMs. 


EPDODDDDODOOOOOODOOOODOOOOOOOIOIOROEIOOOOOOOOOOEOEIOOEOO OE / 
x 

/ - 

/* This is a fragment from the event-handling code */ 
/* to illustrate the two ways of resizing a window. */ 
/* None of these shenanigans are necessary for x/ 
/* epplications, since they can use FindWindowO.  */ 
/* 


x 
BEBE COREA ROCCO CACAO OOOO UES UOC OOO OOOO II / 


typedef int (*PROCPTR)C); 


EventRecord xep; 
register word C; 
WindowPtr window; 
Point pt; 
Rect r; 
long size; 


window = Dp->dCt1Window; 


case mouseDown: /* FindWindow() returns inSysWindow x/ 
pt = ep-?where; /* Keep a copy in global coordinates */ 
GlobalToLocal(&ep-) where); 
if Cep->where.v < Ø) ( 

/* In no-man's land, so must be in zoom box; */ 
/* call WDEF for details */ 
C = (**(PROCPTR *) 
(CCWindowPeek window )~> windowDefProc))(8, 
window, wHit, pass(pt)); 
if (TrackBox(window, pass(pt),c)) ( 
ZoomW indow(window, c, FALSE); 
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resize_window(); /* Readjust data structures 


*/ 
) 


break; 


) 

/* See if it's inGrowIcon */ 

r = window portRect; 

r.top = r.bottom - 15; 

r.left » r.right - 15; 

if (PtInRect(pass(ep-)where),&r)) ( 
SetRectC&r , 160, 164,32767,32161); 
size = GrowWindow(window, pass(pt), &r); 
SizeWindowCwindow, (word size & OxFFFF, 

HiWord(size), FALSE); 


resize_window(); /* Readjust data structures */ 


break; 


Multiple windows 

I haven’t written any DAs that let the user work with 
multiple windows; if I use a second window, it’s always a 
modal dialog. Why? Well, there’s no problem using multiple 
windows. You do have to set windowKind in all of them, so 
the system can identify them as belonging to your desk 
accessory. This means that if any of them have a close box, 
the DA gets the close message when the user clicks it! This 
is apparently why MacLightning has a nonstandard close icon. 
Of course, they could have done what ClickOn Worksheet 
does, and include a menu item to close the second window. 

Professor Mac (Steve Brecher) reports that there is a 
global “called CloseOrnHook at $A88. If it contains a non- 
zero value, _SystemClick will assume it is the address of a 
subroutine to be called whan a DA’s close box is clicked. It 
calls the subroutine instead of closing the DA. On entry to 
the routine, Al contains the DA’s DCE address and A4 
contains the window pointer.” He suggests implementing 
multiple windows as follows: on an activate of one of your 
windows, save the contents of CloseOrnHook and put a 
pointer to your own routine there. On a deactivate, restore the 
previous value. Your routine would close the window or the 
driver as appropriate. The routine must be non-relocateable 
while its address is in CloseOrnHook. 

CloseOmHook is not in the Inside Macintosh index; if 
any reader knows where this is documented, please let us 
know. I received this information just before press time and 
haven’t had the chance to try it yet. 

Segmentation 

It’s possible to segment a desk accessory, which allows 
you to get around the 8K limit Apple suggests. 
Unfortunately, you can’t use the segment loader. This means 
you can’t freely call routines without worrying about which 
segment they’re in. But as long as you group routines 
appropriately, this shouldn’t present a problem (although you 
may have to duplicate some of the common routines in each 
segment). You can call a segment from another segment, if 
you need to. 

The idea behind segmentation on the Macintosh is that 
code is just another resource. The segment loader assumes it’s 
in CODE resources. You can choose any name; I use PROC. 
As long as the entry point is at the beginning of the resource, 
it’s easy to call: 
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/REEREREEREREREAERERSA ER AER ERASER ER EKA AER AKA EAE X / 
/* 

x 
/* This fragment illustrates calling an overlay */ 
/* 

*/ 
/BRERRAAERERAAAEREA ELE REESE RAR A ERE AA RRAA AERA X / 
typedef int C*PROCPTR)C); 


h= GetResourceC' PROC',drvr.rsrc2; /* handle to PROC */ 
if Ch == OL) ( /* Something’ s wrong (can't load) */ 


SysBeep(32); /* Let somebody know */ 
return; /* Don't try to call it! */ 
HLockCh); /* Hold down the PROC */ 
(**(PROCPTR *)h)Cdp, drvr_rsrc, title); /* initialize 
dp,...,title */ 
HUnlock(Ch2; /* Let it float in the heap again */ 


Here are the commands in my makefile to compile this 
segment. Temporary files are written to a RAMdisk, and the 
PROC ends up copied into a file with other resources for the 
DA. 


init: init.c write.h 
cc -tabu init.c -o memory: init.asm 
as memory: init.asm -o memory: init.o 
In -t memory: init.o -o memory: init -1c 
rm memory: init.o 
rgen init.r 
cprsrc -f PROC -15392 init /resource_f ile 


Here’s the file init.r (used by RGen, Manx’s improved 
version of RMaker): 


* Resource file for Init code 
init: 
PROCedrd 


type PROC 
,' 15392 (32) 
memory: init 


Globals vs private store 

Writing in C, it seems slightly more efficient to use 
globals than go through a handle at dCtlStorage to get to your 
variables. You'll probably need a global to get to the DCE 
stuff anyway, so you might as well go all the way. This does 
mean that your variables are in the same place as your code, 
and thus you need one big block of memory rather than two 
smaller ones. 

Development environment 

Despite I-444 of Inside Macintosh, desk accessories are 
usually not written in assembly language...at least at Maitreya 
Design. I use C exclusively. And I don’t have a Lisa. 

Development environments are a matter of preference. 
The main consideration in developing DAs is that you don't 
want to have to install them into the System file. That would 
make the development cycle incredibly slow. I develop with 
the editor QUED on a RAMdisk, and simply install the 
DRVR into QUED (with cprsrc -f DRVR 31 acta 
memory:QUED). This is very handy, since I know I'll have 
to use the editor anyway after trying out some changes. 

It's also possible to create a Fon/DA Mover file and 
open it with DA Key (Lofty Becker's shareware FKEY, easily 
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worth its $5 asking price), but this makes the DA modal, and 
harder to debug. If you prefer, you can use Becker’s Other... 
DA (which is the same thing, implemented as a DA), but I 
can’t spare the DRVR space for that. 

I used to use MDS Edit as my editor, and installed into 
it. This uncovered a bug in the way Edit handles the 
clipboard. If you write a private Scrap type, as well as TEXT, 
Edit will delete your format from the clipboard, leaving the 
TEXT intact. If you write only your own type, Edit leaves it 
alone. Apparently it really likes TEXT scraps, and will do 
anything to keep them pure. I know of no workaround to this 
problem (short of using QUED). 

To save time in development, a desk accessory that uses 
resources should have an OpenResFile() call at the beginning 
to open a separate resource file. This means you won't have 
to copy resources which are essentially static during the 
development process. When you finish the DA, it's a simple 
matter to copy the DRVR into the resource file and change its 
type and creator to DFIL DMOV so it can be opened by the 
Font/DA Mover. 

Debugging 

ResEdit is a harsh environment to try your DA in 
because of the magic things it does with resource files and the 
order in which they're searched. I've also been told that MDS 
Edit is a harsh environment for DAs, but I haven't seen why 
except for the clipboard bug. Many Microsoft programs 
manage memory poorly, and are an ideal place to make sure 
your DA can live with a small heap. Of course, you have to 
figure out which bugs you uncover are yours, and which are 
Microsoft's (Word, for example, doesn't handle menus well). 

All the usual debugging techniques apply, like using 
Discipline and Heap Scramble from TMON. 

Installer 

It'S definitely not worth writing your own installer, in 
my opinion. There's no need to reinvent the wheel. 
According to people who've written them, they're a pain (this 
should be easy to verify by observing the many revisions to 
Apple's Font/DA Mover). The only reason to write your own 
installer is if your desk accessory is something else 
masquerading behind a desk accessory interface (like Tempo) 
and has resources which can't be numbered as owned (such as 
INITs). 

Copy protection 

Yes, you can protect a DA. But don't. 

Pitfalls 

One of the most annoying things Apple’s done is to 
reduce the number of DRVR slots available to desk 
accessories. Font/DA Mover enforces the restriction of not 
installing more than 15 DAs (it’s possible to install up to 20 
using ResEdit, but this option isn’t available to the average 
user). This suggests one of two conclusions: make your DA 
either modal, or versatile. Modal, because if a user runs a DA 
via DA Key, she won't be able to get at the main application 
until she closes the DA. Versatile, because it doesn't make 
sense to have a DA that renames files, another one to delete 
files, and a third to set file attributes. DA slots are too scarce 
to squander that way, and if you write DAs like that, nobody 
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will want to install them. Of course, you have to watch out 
for creeping featurism. 

Remember that, if you're given a close call, you must 
close. The close may have been issued by the Finder, closing 
all open DAs before launching an application. There's no Way 
a DA can put up a Cancel button for that! 

If you write in a high-level language, being called from 
the ROM may present a problem. This usually happens in 
cases like a TextEdit clikLoop or a Standard File filterProc. 


The problem is that register A4 won't pont to your globals. 
This may not be a real problem in the RVR, but a segment 


has no way of determining the correct value of the global base. 
The inline assembly feature of Aztec C saved me; I simply 
added instructions to save A4 before calling a ROM routine 
which called me back, and restore it before returning to the 
ROM. It would be possible to save your global base in 
memory you've allocated and have a handle to in dCtlStorage; 
you could get at your DCE from the Unit Table using the 
method in Apple's Technical Note 71. This method requires 
knowing the name of the DRVR, however, and you can't be 
certain of your own name (I routinely change DA names in 
my system to shorten them or remove Ms), 

I don't know if reentrancy is really a pitfall, but you have 
to remember that ModalDialog calls SystemTask, and you'll 
get activate and update events. 

JIODone and locking have been covered already 
(MacTutor, Apr 86). I'll just add that if you unlock yourself, 
be sure to keep any references to routines saved in data 
Structures (such as a TextEdit clikLoop) current when you're 
again locked. 

Renumbering really shouldn't be a pitfall either, but you 
do have to be sure your resource IDs aren't hardcoded, because 
Fon/DA Mover will renumber all your resources. This 
routine figures out what they're renumbered to. 


EEE ECACC SASSO OOOO UCI OCICS OO OO a / 


/* 


x 
/* GET_DRVR - Find resource number, based on the driver */ 
/* 

x 


[PEEPEEEEEEUOOOOOOODEEOEEEEROROOOOODODODO OO ODIO OO ORG / 


get drvr(C) ( 
return 0xC000 | (CC-Dp dCtlRefNum) - 1) «< 5); 


A lot of development systems don’t Support desk 
accessories too well. MacTutor has had numerous articles on 
the difficulties of using different compilers. Using Aztec C, 
I've found bugs in the Memory Manager glue code, where the 
reference to the memerr global was A5 relative, and might 
mean that different segments had different globals. Rewriting 
the glue and including it in my own source code (instead of the 
library) solved this. 

Friendly Applications 

The other side of the DA Story is that applications have 
to support them. You might as well, because someone's 
going to use DA Key on you and use DAs anyway. So your 
clipboard and files could be changed out from under you, and 
all your resources purged. 
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And you’re doing the user a disservice if you don’t. For 
example, I find playing adventure games more enjoyable if I 
can open a DA to take notes or draw a map. And Apple’s 
MiniFinder is useless without desk accessories. 

Treat DAs as coequal applications. The user will expect 
the same behaviour from any open window. Don’t do 
anything a DA can’t. I always thought Multiplan, with its 
multiplicity of cursors, was silly. For example, the cursor 
changed to a multi-directional arrow when in the draggable 
title bar of a window. Unless, of course, the window was for 
a desk accessory... In this case, I think inconsistency was the 
hobgoblin of small minds. 

Since so few DAs are written to handle goodBye kisses, 
it’s a good idea to close each open desk accessory before 


quitting. 

Don’t force the user to memorize keyboard commands. 
Even if your application doesn’t handle the Edit menu, include 
one for the benefit of desk accessories. And don’t forget Undo, 
even if you have to dim it when your window’s active. 

Try to use normal windows. It’s always bothered me that 
I have to close desk accessories before resuming work in 
MacPaint. 

Don’t gobble up the DA menu with stuff that has 
nothing to do with DAs. Jazz is a big offender here. Thank 
goodness updated Systems have scrolling menus. 

Let DAs have memory! Certain applications such as 


Microsoft Basic do their own memory management, and don’t 


o 


cic 


leave enough for DAs. 
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PostScript Printing 


Place PostScript in MacWrite Documents 


Embed PostScript in Fonts and Pictures 


When a Macintosh application prints to Apple's 
LaserWriter printer, the Printing Manager converts the 
sequence of QuickDraw operations that the application used to 
image the document on the screen into a PostScript® program 
that describes the appearance of the document on printed pages. 
The Printing Manager then transmits this program to the 
LaserWriter, which contains a PostScript interpreter bundled 
with a xerographic marking engine. The interpreter executes 
the page description and produces output on the attached 
output device. 

The PostScript language itself was designed by Adobe 
Systems, Inc. to be a high-level, device independent page 
description language with powerful text and graphics 
capabilities. PostScript includes operators to outline or fill 
any arbitrary graphical shape constructed from Straight lines, 
arcs, and cubic polynomical curves; to treat any shape as a 
clipping path to crop any other graphics; and to render text and 
sampled images of arbitrary resolution at any size or angle on 
the page. 

Quickdraw versus PostScript 


Normally, PostScript programs are generated 
automatically by the Printing Manager when the application's 
client selects the Print command. Let us briefly review how 
this is done. On the Mac, all drawing is done through the 
quickdraw routines. On the Laser, all drawing is done through 
PostScript. Hence quickdraw calls must be converted to the 
closest PostScript equivalent. Quickdraw is designed so that 
all the quickdraw routines reduce down to a dozen or so 
standard drawing routines. This lets an application designer 
write his own quickdraw routines by replacing these primary 
routines or "quickdraw verbs" with his own. The Print 
Manager converts each of these quickdraw verbs to a call on a 
PostScript procedure, which closely emulates the quickdraw 
action using PostScript primitives. The definition of that 
procedure is contained in Laserprep, which is downloaded into 
the Laserwriter. The PostScript procedures defined in the 
Laserprep file in effect re-define the quickdraw verbs in terms 
of PostScript commands. When you use the command-F key 
to produce a PostScript file, the Print Manager generates a file 
of procedure calls into this Laserprep file. So you couldn't use 
this PostScript file without the Laserprep file being 
downloaded into the Laserwriter first. Thus in normal printing, 
the Mac quickdraw environment is completely translated to a 
PostScript environment automatically through the actions of 
the Printing Manager and Laserprep. This automatic 
conversion is very useful, since neither the application's user 
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nor its designer need to understand or worry about the details 
and concerns of the PostScript environment. 

There are several situations, however, when it would be 
useful to type or paste raw PostScript commands directly into 
a document, so that the images generated by the commands are 
integrated on the printed page along with the rest of the 
document. The reason for this is that neither QuickDraw nor 
current applications are capable of imaging the full repetoir of 
PostScript graphics on the screen. Hence, many of the 
LaserWriters powerful capabilities remain relatively 
unexplored and unexploited, at least when using MacWrite, 
MacDraw and MacPaint. And since the Laserwriter costs some 
$4800, it would be nice to be able to use all of it's 
capabilities! 

But there is lots of good news on the horizon. Apple's 
new Printing Manager, version 3.1, contains several useful 
facilities for including PostScript in a document. Apple is 
madly documenting its capabilities. As a preview, we'll look 
at what you can do with them. 


The “PostScript Escape” Font 


The new Printing Manager treats any text in the font 
named “PostScript Escape” as PostScript commands and sends 
the text straight through to the LaserWriter. When the Print 
Manager sees text displayed in the PostScript Escape font, that 
text is not converted into a Laserprep text drawing call, but 
simply inserted into the rest of the PostScript file. In this 
way, pure postscript is included in this file of Laserprep calls 
and executed directly by the laserwriter. 

Any font may be used as the "PostScript Escape" font, 
but consider this example using the font I've created (available 
on source code disk #9 from the MacTutor mail order store). 
Here is an example. First, type the following PostScript 
program into the middle of a MacWrite document: 


gsave initgraphics 
/Times-BoldItalic findfont 27 scalefont setfont 
/rays 
( 0 1.5 179 
( gsave rotate Ø Ø moveto 108 Ø lineto stroke grestore ) 
for 
def 


) de 
300 400 translate .25 setlinewidth 
newpath Ø Ø moveto (StarLines) true charpath clip 
newpath 54 -15 translate rays 
grestore 


Then hilight the whole paragraph, and select my PostScript 
Escape font from MacWrite's Font menu. The paragraph will 
disappear! Now print the document. The effects of the 
embeded postscript will appear in the LaserWriter printout. 
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Invisible Fonts 


Whats going on? First, my PostScript Escape font is 
invisible! Using Apple's ResEdit, I made a copy of the Times 
12 point font and called it PostScript Escape. Then I erased 
all of the black bits in the entire font and set the width of each 
letter to zero. Then I reduced the ascent and descent so that the 
font is only 1 point tall. Finally, I pasted the font into my 
System file. You can do the same thing to create this font if 
you don't want to wait to get it on a source code disk. 

Why bother with an invisible font? If the PostScript 
Escape font was visible, then any PostScript set in it would 
leave blank areas on the printed page, since MacWrite assumes 
that the text will be printed as it appears on the screen. Since 
only the graphic objects that the PostScript produces are 
visible on the printed page, we have no choice but to make it 
invisible, otherwise we would loose screen- page fidelity. 

How does one edit invisible text? Easy, just select 
something that includes the PostScript and change the whole 
thing to Times, for example. Edit the PostScript, make it 
invisible again, and print. 


PostScript Considerations 


When you imbed normal postscript in MacWrite, your 
postscript image will come out upside down. This is because 
the coordinate reference system for quickdraw and postscript are 
Opposite. You fix this by adding in front of the postscript two 
calls: 

gsave initgraphics 
now add your postscript stuff 
grestore 


This has the effect of saving the Print Managers 
coordinate system, initializes the default postscript coordinate 
system, then it draws the postscript, and finally restores the 
print manager's coordinate system. In PostScript, (0,0) is at 
the bottom of the page, while in quickdraw (0,0) is at the top 
of the page. In our example above we have added these 
commands so the PostScript has the same orientation as the 
rest of the Macwrite file. 

Another problem is placement. Paste the postscript at the 
bottom of the page, so the Macwrite stuff does not overwrite 
the postscript image. Or if you estimate where your figure 
should be placed on the page, you can leave space in the 
Macwrite document for the figure, and place your postscript 
stuff in the blank box, but remember you have to set your 
postscript coordinates in your postscript commands to match 
that box area. The Print Manager doesn't tell you where it is 
on the page! 

Pagemaker Doesn't Work! 


Pagemaker does not use the default Print Manager 
routines, which makes calls on Laserprep. Rather it calls it's 
own RAM based Print Manager in Pagemaker which makes 
calls on Aldusprep, and this Pagemaker Print Manager does 
not know about this PostScript escape routine so it will be 
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treated like a regular text font, and hence there still is no way 
to imbed PostScript into your Pagemaker layout! Pagemaker 
is supposed to be updating their product to support these new 
print manager functions sometime this summer. They will add 
a PostScript place command to place PostScript text files in a 
manner similar to placing a MacWrite file. A quickdraw 
picture feature will allow the quickdraw picture to represent the 
postscript stuff and make placement on the page as easy as 
placing a MacDraw figure. If they can pull this off in a timely 
manner, it will greatly increase the sophistication level of 
Pagemaker in the marketplace. 
Get a copy of PostScript Language Reference Manual 
and PostScript Language Tutorial and Cookbook, by Adobe 
Systems and published by Addison-Wesley and use this 
technique to try out some of the examples. 


PostScript in Pictures 


The new Printing Manager also has some goodies for 
those of you who use QuickDraw pictures. Try embedding the 
following C code into a picture or place them between a 
PrOpenPage and a PrClosePage in your printing loop: 


C Code Example 
open pictureCerect); 
fillrectCérect, white); 
PicComment(198, Ø, 81); /* Begin PostScript mode */ 

/* Send following Quickdraw text as PostScript */ 
PicComment(194, Ø, 21); /* this is postscript escape font 
*/ 


DrewTextC"/pgsave initgraphics"); 
DrawText("\p/Times-BoldItalic findfont 27 scalefont setfont"); 
DrawText("\p/rays"); 

To /* add postscript commands */ 
DrawText("\pgrestore"); 


PicCommentC191, Ø, 21); 
close picture; 


/* End PostScript mode */ 
Print Manager Bug 


The fillrect simply draws a white rectangle to get around 
a bug in the print manager which causes it to think this is a 
blank page unless it sees at least one quickdraw drawing 
command. The white rectangle on white obviously won't do 
anything we can see, but it will force the Print Manager to 
then show our postscript stuff rather than a blank page. 

These PicComment calls are intercepted by the Printing 
Manager. Comments 190 and 191 bracket the PostScript, and 
comment 194 tells the Printing Manger that the following 
text is set in the PostScript Escape font, so the Printing 
Manager simply forwards all of the text to the Laserwriter. 


The Parkhurst Picture 


What else does the Printing Manager do? A while back 
Bill Parkhurst, author of the T/Makers ClickArt Effects 
package, argued that each QuickDraw Picture should have two 
forks - a QuickDraw fork and a PostScript fork. When such a 
picture is drawn on the screen or printed on the ImageWriter, 
only the QuickDraw fork is used. When it is printed on a 
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PostScript printer, only the PostScript is used. You get the 
best of both worlds, good looking printed documents and good 
screen approximations without the need for a PostScript 
interpreter resident on the Macintosh. Apparently, version 3.1 
has some support for the Parkhurst Picture, but details have 
yet to be documented, and there is some doubt whether the 
implementation will work in the current version. It is not 
known if Apple is planning to support this untested code 
features. 

Downloadable font problems: With this implementation 
of PostScript escape, a needed downloaded font will not be 
donwloaded unless the font is used in the regular quickdraw 
portion of the file. 

Laserwriter Plus RAM memory problems: One of the 
great mysteries is why Apple did not increase the RAM 
memory in the Laserwriter Plus so that downloadable fonts 
could be supported. As it is now, only one small font can be 
downloaded at a time due to the fact that only about 50K of 
RAM is left. Application programs could be designed to get 
around this problem by imaging the page one font at a time, 
rather than composing all the page at once. The page should 
be reorganzied by the application by font, so that each font 
component is sent only once to the printer. An ascii postscript 
file sort program that sorts the postscript by font and sends it 
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to the printer in the sorted order, using one font at a time on a 
page basis would be a great utility program. It also would be 
great to design this abilitiy into existing page makeup 
software. | 

Another fix is to use the note operator which allows 
drawing in a smaller area on the page in one of three page 
Sizes: letter, note and legal. Using note size, the RAM 
previously allocated for the whole page area is now smaller by 
100K, which can be used by fonts so up to 4 downloadable 
fonts can be supported, but you have to use the note operator 
in your own postscript file. The Print Manager uses the note 
operator automatically. The Page Setup allows you select 
between note size (7.7 by 10.2 on a page 8.5 by 11) and legal 
size (6.7 by 13 on an 8.5 by 14 inch page). Letter size (8 by 
11 on a 8.5 by 11 inch page is not supported by the Print 
Manager, which is why you can't print to the edge of the page. 
The note operator can select letter size in a custom postscript 
file however. Aldus prep does not use the note operator. 
Because there is not enough RAM memory in the Laserwriter 
Plus or the Laserwriter, you can't have both a full size page 
and downloadable fonts. 
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C Workshop 
Mouse DA shows off Fat Bits 


Mouse Position Desk Accessory 
Introduction 

Setting up screen graphics on the Mac can be a very tedious 
and time consuming job. Previously I have used "Mouse 
Position" desk accessories (DA's) to show the position of the 
mouse, but none of them had the features I wanted. So as a 
true programmer I wrote one myself. I borrowed some ideas 
from others and added a few new ones of my own. 

First, I must give credit where it is due. I used an old DA 
called Magnifying Glass to get a "Fat Bits" view of the screen. 
I really thought the "Fat Bits" was neat, but wanted other 
information. This Mouse Position DA also has this feature, 
but uses it in a little different way. 

Using the Mouse Position DA 

The window created by the Mouse Position DA looks like 

this - 


[] Mouse Pos 
MacWr i te/Paint 


The top line gives the name of the window the cursor is 
currently over. The next two lines (labeled 'L' and 'G’') give the 
local and global coordinates of the mouse (both horizontal and 
vertical portions are given). The bottom graphics give a "Fat 
Bits" view of the mouse position. There are a few differences 
between these "Fat Bits" and others you may have seen. 

First, the actual position of the cursor is in the center of the 
screen (not in the top left corner). Second, the gray lines 
symbolize the real point (as you all know from reading Inside 
Macintosh - points do not occupy space, they are at the 
intersection of infinitely thin horizontal and vertical grid 
lines). The "hot spot" of the cursor is the point immediately 
below and to the right of the gray "crosshairs" (the tip of the 
paintbrush of the MacPaint Icon shown in the window). The 
"crosshairs" do not cover up any pixels, they just split the 
rectangle surrounding the cursor into four planes. 

There are also a few other features in this DA - 

« when the mouse is over the desktop, the window name is set 
to "DeskTop" and no local coordinates are shown (since 
they don't exist). 

e the window name, local, and global coordinates can be "Cut" 
or "Copied" to the clipboard and "Pasted" into your 
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C] Mouse Pos 
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Rick Flott 
FlottWare 
Chandler, AZ 


e when the CapsLock key is down and the coordinates are Cut 
or Copied, they are appended to the clipboard. This is very 
handy when setting up rectangles or other complex graphics 
that require multiple points. Just press CapsLock and start 
Copying! 

e remember - in most applications Cut and Copy only work 
on the topmost window, hence the Mouse Position window 
must be in front for these commands to work. 

Code Description 
As in any desk accessory, 5 routines must be present - 


* open (initializes the DA) 

e close (stops the DA) 

* control (receives commands from system) 
* prime 

e status 


The latter two routines do not need to perform any 
functions, but they must be present. 

The open routine in the Mouse Position DA is the 
"main()" of this C program. It allocates the DA window 
from the heap, sets up the font for this window, and draws the 
"static" portion of the window. It also stores the reference 
number of the DA in the windowKind field of the window. 
This is very important since this the only way the Mac knows 
that this is a "system" window and to pass the proper events 
to it and not to the running application. In addition to this, the 
pointer to the window is kept in the device control entry for 
retrieval later on. Remember, a desk accessory is viewed as 5 
separate routines called by the system (unlike an application). 

The Close routine does the opposite of the open. It releases 
the memory used by the window and resets the proper 
fields in the device control entry record. 

The Control routine does all the work. It takes 
commands from the system (passed to it when the application 
calls SystemTask, SystemEdit, or SystemClick) and processes 
them. In this DA, only two commands are processed - accRun 
(periodic command telling the DA to run) and accEvent 
(command telling the DA to handle an event). As you will see 
later on, this DA is set up to run as often as possible so that 
the mouse position coordinates appear to be updated 
continuously in the window. 

This routine starts off by obtaining the window pointer 
from the device control entry and parsing the command 
(CSCode) sent to it. If it is a run command (accRun) then the 
new mouse position is displayed (by calling the routine 
dspMousePos). If it is the event command (accEvent) then 
the doEvent routine is called. 

The doEvent routine handles 4 types of events - keyDown, 
autoKey, updateEvt, and activateEvt. The updateEvt will re- 
draw the coordinates and the window name. The activateEvt 
only re-draws the coordinates. The keyDown and autoKey 
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events do most of the work in this code. When either of these 
events occur, a string is allocated, the coordinates and window 
name placed into the string (with the Munger ROM call), and 
moved to the clipboard. 

Why did I append perfectly good strings into another string? 
I'm lazy I guess (plus the string is temporarily allocated off 
the heap and is released immediately). Notice that if the Cut or 
Copy keys are capitals (the CapsLock key is down) then the 
current TEXT contents of the clipboard are placed in the 
string. This allows the user to "append" coordinates together 
as previously described. 

The dspMousePos routine first gets the current 
coordinates of the mouse. If the mouse has moved from the 
last time this routine was called, then processing continues, 
otherwise this routine just returns. This keeps down the 
"flicker" of the display, since the window is only updated 
when the mouse moves. It also keeps the DA from being a 
CPU hog. 

Next, the name of the window the mouse is currently over 
is retrieved. If it is a different window than the last time, the 
new name is displayed (by the routine dspWindowTitle). 

If the mouse is not on the desktop, then the local 
coordinates must be recomputed. GetMouse gives the mouse 
in local coordinates of the active window, not the window the 
mouse is currently over (which may be inactive or even 
invisible). Hence, the local coordinates must be recomputed 
with respect to the window the mouse is over. The rest of this 
routine is straightforward. 

The coordinates are converted to strings, the "h" and "v" 
characters are appended to them, and these strings are displayed 
right justified in the window. Next, the four "Fat Bit" 
rectangles are displayed. Notice that 24 pixels surrounding the 
cursor in the horizontal direction and 16 pixels surrounding the 
cursor in the vertical direction are displayed (using CopyBits) 
in the window. 

The dspWindowTitle routine first determines if the 
window passed to it is the desktop or a real window. If it is a 
real window, then its name is retrieved. Otherwise the name 
" DeskTop" is used. It then displays this name center justified 
in the DA window. It also adds a carriage return (n) to the 
name so that when the name is Cut or Copied to the 
clipboard, the coordinates will be on the next line (like in the 
window). 

The drawWindow routine just draws the "static" portion 
of the window. This includes the "G" and "L" characters, the 
horizontal dividing lines, and the gray "crosshairs". 

Consulair's DeskMaker 

Now all of you desk accessory veterans are saying - "this 
stuff will never work, look at all of the global variables this 
guy has in a DA". Well, an application called DeskMaker by 
Consulair (included with their Mac C development system) 
takes alot of the headache out of writing DA's. After talking 
with Bill Duvall, he informed me that the way DeskMaker 
works is that it takes all of the global variables (referenced off 
of A4 by the #Options R=4 line) and makes them part of the 
DRVR resource (he appends them to the end of the code). This 
allows them to be global and still be accessed by the code in 
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the DA. Of course, I didn't call him until I had already stayed 
up all night allocating my globals from the heap and accessing 
them through a handle. Oh well, it wasn't the first time I 
threw out code, and it won't be the last. 

In addition to this, DeskMaker takes commands from a 
"desk" text file to set up the DA's flags and header constants 
they require. You can turn any flag on or off, set up the other 
constants (like drvrDelay, drvrMask, etc.), and specify the 
names of the standard routines (Open, Close, Control, etc.) He 
has also added another command "Test" which allows you 
temporarily install the DA in the system menu to try it out. 
This is nice since you do not have to use Font/DA Mover or 
any of the other applications/DA's that run DA's from a file. 

The "MousePos.Desk" listing shows the commands sent to 
DeskMaker for this DA. First, the filename, map, and name of 
the DA is set up. Next, the names of the 5 routines are 
defined. Finally, the drvrEMask, drvrDelay, and drvrFlags are 
set up. This DA was given the ID of 22 and the test flag was 
set to allow debugging. Since most of the C compilers handle 
DAs differently, this information should allow you to recreate 
this DA on other compilers. 

MousePos.c Lisiting 


[RERRREAERKERAE EKER ERK EER REESE KAA K ERE RKA AKER EAA EEK ERKKEREK 
MousePos.c 


This is a desk accessory that shows three things about 
the position of the mouse cursor - 


- Name of the window the cursor is currently over 
- Local and global coordinates of the cursor 
- “Fat Bits" display of a rectangle around the cursor 


It also allows the user to Copy or Cut the window name 
and the local & global coordinates to the clipboard (CapsLock- 
Copy or CapsLock-Cut will append the coordinates to the 
Clipboard). 


Written by: Rick Flott Mac C 
(Consulair) V 4.5 
DOOOOCOCODOOOOEOOOOOOPDEOOOOEEOEOOODOUOEOIOOEOOEOEOOOOEEOOOOOEOEEOEOEOEOEE / 


"Options R=4 L-500 F-8000 Z Q-0 0-200 


®include "MacCDefs.h" 
include "Events.h" 
*include "Window.h" 
8Sinclude "Font.h" 
include "TextEdit.h" 
8include "Osmisc.h" 
*include " 
8include "Desk.h" 


// Mac ROM data structure def's 


8def ine FALSE Ø 
8def ine TRUE ØxFF 


en struct // 6 char strings for the coord's 
char count; 


char s[6]; 
) Str6; 
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/* —-- Rectangles ---- */ 
Rect titleRect = ( Ø, Ø, 10,100), // Window title 
rect 
localStrRect = (11, 1, 21, 6), 
loca lHRect = (11, 6, 21, 49}, // Local horiz 
coord's rect 
localVRect = ( 11, 52, 21, 94), // Local vert 


coord's rect 
globalStrRect = (21, 1,31, 6), 
globalHRect = (21, 6, 31, 49), 
coord's rect 
globalVRect = ( 21, 52, 31, 94), 
coord's rect 


// Global horiz 
// Global vert 


fBTopLeftRect = (32, Ø, 64, 48), // “Fat Bits" rect's 
fBBotLeftRect = (68, 0,100, 48), 
fBTopRightRect = ( 32, 52, 64, 100), 
fBBotRightRect = ( 68, 52, 100, 100), 
windowRect = (50, 5,150,105); // DA window rect 
[F en Strings ------ x/ 


char  deskTopTitlel] = ("\pDeskTop"}; // Constant desktop str 


Stró localVStr, localHStr, 
globalVStr, globalHStr; 


// Local coord strings 
// Global coord strings 


Str255 windowT; // Window name string 
/* --- Global Var's --- */ 


WindowPtr oldFrontWindow = Ø; 
Point oldPt = (0,0); 


struct QDVar *getQDC); 


// Last front window ptr 
// Last position of mouse 


maint) (Open routine) 


The Open routine opens the desk accessory window and 
intializes any global data before the desk accessory is used 


a d ditta: 7 
int main(parameterBlock, DeviceControlEntry) 
Cntr 1Param *parame terB lock; 
DeviceControl *DeviceControlEntry; 
WindowPtr windowPtr ; 
GrafPtr port; 
if CCwindowPtr = DeviceControlEntry-»dCtlWindow) == Ø) 
GetPort(&port); // Preserve appl window 
/ Open DA window 
windowPtr = NewWindowCO, &windowRect, 
"\pMouse Pos",@, 
rDocProc, -1, 1, Ø); 
if CwindowPtr == 0) 
return(-1); 
SetPort(windowPtr ); // Use this new window 
// Set it as a system window 
CCWindowPeek )windowPtr )->windowKind = 
DeviceContr 


olEntry-? dCt Ref Num; 


/ Save DA window ptr 
DeviceControlEntry- dCt 1WindowzwindowPtr; 


TextFont(monaco); // Set up DA font 
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TextSize(9); 


drawW indow(); // Draw static portion of window 
OE cee // Restore application window 
return 9; 


) // end main) 


Close() 
The Close routine disposes of the desk accessory window 


and any data 
allocated on the heap. 


int CloseCparameterBlock, DeviceControlEntry) 
Cntr 1Param *parameterB lock; 
DeviceControl *DeviceControlEntry; 
WindowPtr windowPtr; 

// Get DA window ptr 
windowPtr = DeviceControlEntry-? dCtlWindow; 


DisposeWindow(windowPtr); // Release DA window 
DeviceControlEntry-?dCtlWindow = Ø; 


return 9; 


) // end Close() 


PrimeC) 
This desk accessory does not use a Prime routine. 
PrimeCparameterBlock ,DeviceControlEntry) 


Cntr 1Param *parameterB lock; 
DeviceControl *DeviceControlEntry; 


Status(parameterB lock, DeviceControlEntry) 


This desk accessory does not use a Status routine. 


Status(CparameterBlock, DeviceControlEntry) 
Cntr 1Param *parameterB lock; 
DeviceControl *DeviceControlEntry; 


Controlc) 
The Control routine parses the desk accessory command 
sent from the system and routes the data to the proper 
routine. The commands currently used are - 


accRun - Display the mouse position. 
accEvent - Handle Cut and Copy menu commands. 


Control CparameterBlock, DeviceControlEntry) 
Cntr 1Param *parameterBlock; 
DeviceControl *DeviceControlEntry; 


GrafPtr port; 
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WindowPtr windowPtr; 
// Get DA window ptr 
windowPtr = DeviceControlEntry->dCt1Window; 


GetPortC&port); 


// Preserve application window 
SetPort(windowPtr); 


// Use DA window 
em (parameterBlock-»CSCode) // What cmd was sent? 


cese accRun: / 
dspMousePos(windowPtr ); 
break; 

case accEvent: // cmd = HANDLE EVENT 
doEvent (parame terBlock-)>csp.event, windowPtr ); 
break; 

) // end switch 


/ cmd = RUN 
// Display new position 


SetPortCport); // Restore app] window 


) // end Contro1() 


doEvent() 


Thie routine parses the event sent from the system. The 
events currently used are - 
keyDown, 


autoKey - Cut or Copy the window name & 


mouse coord's to clipboard. 


updateEvt - Redraw the entire desk acc window. 


activateEvt - Redraw the only the mouse coord's. 


doEventCevent, windowPtr) 
EventRecord *event; 
WindowPtr windowPtr; 


Handle strHandle; 
Ptr — strPtr; 

int screpOf fset; 
long offset = Ø; 
switch Cevent-> what) // Which event occurred? 
case keyDown: 
case autokey: // Event = KEY PUSH 

if (Cevent-? modif iers&cmdKey )) // Was it a cmd key? 


strHandle = CHandle)NewHandle(0); // Allocate a string 


// Only allow Cut, Copy 
ae (Cchar )Cevent-> message )) 


case 'C': 
case 'X': 
offset = GetScrap(strHandle, 
TEXT ' , &ScrapOffset); 


// If Shift/CapsLock, copy previous clip 


case 'c': 
case 'x': 

if Coffset < Ø) // Was there a scrap error? 
SysBeep(2); 
ii 


// Y - return 


T (ZeroScrepC?) // Clear the clipboard 


SysBeep(2); 
Po 
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// Grow string to place clipboard stuff in 


Se tHandleSize(strHandle, of fset+ 
(sizeof windowT)+ 
(sizeof localHStr)+ 
(sizeof localVStr )+ 
(sizeof globalHStr)+ 
(sizeof globalVStr)); 


// Place window name, local, global coord's into 
string 


offset = Munger(strHendle,offset,0,0,windowT.s, 
Clong?windowT .count); 
offset = Munger(strHandle,offset,0,0, localHStr.s, 
Clong)localHStr.count); 
offset = Munger (strHandle,offset,0,8, localVStr.s, 
Clong)localVStr.count); 
offset = Munger (strHandle,offset,0,8,globalHStr.s, 
Clong)globalHStr.count); 
offset = Munger(strHandle, of fset,0,8,globalVStr.s, 
Clong?globalVStr count); 
HLockCstrHandle); // Lock the string down 
strPtr = (Ptr)*strHandle; 
// Put string into clipboard 
if CPutScrap(Clong offset, 'TEXT' ,strPtr)) 
SysBeep(20); 


HUnlockCstrHandle); // Unlock the string 
break; 


default: 
SysBeep(2); 
break; 


// Beep on other cmd keys 


) // end switch 


DisposHandle(strHandle); 


// Release the string 
) // end if 


return; 


Cese updateEvt: // Event = UPDATE EVENT 


SetPort(windowPtr); // Use DA window 
BeginUpdate(windowPtr); 
drawWindow(); // Redraw the window 


// Display new window title 
dspW indowTitleColdFrontWindow); 
EndUpdate(w indowPtr); 
return; 


case activateEvt: // Event = ACTIVATE EVENT 
dspMousePos(windowPtr); ^ // Display new mouse pos 
return; 

) // end switch 
) // end doEvent() 


dspMousePos(C ) 


This routine displays the position of the mouse. It 
displays the following information - 


- Local and global coordinates of the cursor 
- "Fat Bits" display of a rectengle around the cursor 


dspMousePos(windowP tr) 
ioe windowPtr; 


Rect cursorRect; 
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WindowPtr mouseW indow; 


short windowCode; 
struct — QDVar *myQD; // Place for copy of QD pointer 
Point localPt,globalPt; 


myQD = getQDC); 


GetMouse(&localPt); 
globalPt = localPt; 
LocalToGlobal(&globalPt); 


// Get a copy of QD pointer 

// Get the new mouse position 
// Convert it to global coord's 
^ ClEqualPtC&globalPt,&oldPt)) // Has the mouse moved? 


oldPt = globalPt; // Y - remember where it now is 
// Determine the window the mouse is now in 
windowCode = FindWindow(&globalPt, 
&mouseW indow ); 


// Is mouse in a different window? 
if ColdFrontWindow != mouseWindow) 
// Y - Display title of new 
window 
dspWindowTitleColdFrontWindow = mouseWindow); 
if CmouseW indow) // Is the mouse on the Desktop? 
// N - get, display local coord's 
// Get local coord's of window mouse is in 
SetPort(mouseWindow); 
localPt = globalPt; 
Global ToLocal(&localPt); 
// Convert local coord's to strings 
NumToStr ingClocalPt .h, &localHStr); 
NumToStr ingClocalPt.v,&localVStr); 


localHStr .s(localHStr.count**]s'h'; // Add in 'h' 
and 'v' 

localVStr .s(localVStr.count**]s'v'; 

localVStr .s{localVStr.count++]='\n'; // Add CR 

else // Y - don't display local coord's when on 


desktop 
localHStr .count=localVStr .count=@; 


SetPortCwindowPtr ); // Draw in desk acc window 
// Convert global coord's to strings 
NumToStr ingCglobalPt .h, &globalHStr); 
NunToStr ingCglobalPt .v, &globalVStr); 
globalHStr .s{globalHStr .count++J='h'; // Add in 'h' and 
globalVStr .s{globalVStr .countt+]='v' ; 


globalVStr.s(globalVStr .count+t+J='\n'; // 
Add CR 


// Display global coord's 
TextBoxCglobalHStr.s,globalHStr.count, 
&globalHRect, - 1); 
TextBox(CglobalVStr.s,globalVStr.count, 
&globalVRect, - 1); 
// Display local coord's 
TextBoxClocalHStr.s,localHStr.count, 
&localHRect,-1); 
TextBoxClocalVStr.s,localVStr.count, 
&localVRect,- 1); 


SetRect(&cursorRect, — // Set up top left "Fat Bits" rect 
globalPt.h-12,globalPt.v-8, 
globalPt.h, globalPt.v); 
CopyBits(&myQD-»screenBits, // Display top left "Fat 
Bits" 
&windowPtr-»portBits, 
&cursorRect, &f BTopLef tRect , srcCopy, 8); 


162 


SetRect(&cursorRect, // Set up bottom left "Fat Bits" 
rect 
globalPt.h-12,globalPt.v, 
globalPt.h, globalPt.v*8); 
CopyBitsC&myQD-? screenB its, // Display bot left "Fat 
Bits" . 


&windowPtr->portBits, 
&cursorRect, &fBBotLef tRect, srcCopy, 8); 


SetRect(&cursorRect, // Set up bottom right "Fat Bits" 
rect 
globalPt.h, globalPt.v, 
globalPt.h*12,globalPt.v*8); 
CopyBitsC&myQD-»screenBits, // Display bot right "Fat 
Bits" 
&windowPtr->portBits, 


&cursorRect, &fBBotRightRect,srcCopu, 8); 


SetRect(&cursorRect, // Set up top right "Fat Bits" rect 
globalPt.h, globalPt.v-8, 
globalPt.h*12,globalPt.v); 


CopyBitsC&myQD-»screenBits, // Display top right "Fat 
Bits" 
&windowPtr-?portBits, 


&cursorRect,&fBTopRightRect, srcCopy, 0); 


) // endif 
) // end dspMousePos¢ ) 


dspWindowTitleCO 


This routine displays the name of the window passed to 
it in the window title rectangle--- 


dspWindowTitleC(windowPtr) 
WindowPtr windowPtr; 
if (windowPtr) // Is the mouse in a real window? 
// Y - display window's name 
GetWTitleCwindowPtr,&windowT2; 
else // N - display the desktop name 
BlockMoveC&deskTopTitle[2],&windowT,deskTopTitle(21*1); 


TextBoxCwindowT.s,windowT.count,&titleRect, 1); 
windowT.s[windowT.count*t*] = '\n'; // 
Add CR 


) // end dspWindowTitleC) 


drawWindowC) 


This routine draws the "static" portion of the window. 


drawW indow() 


struct QDVar *myQD; // Place for copy of QD pointer 


myQD = getQDC); // Get a copy of QD pointer 
MoveToCglobalStrRect.left, // Draw "GC" 


globalStrRect.bottom - 1 ); 
DrawChar('G'); 


MoveToClocalStrRect left, // Draw "L" 
localStrRect .bottom - 1); 
DrawChar('L'); 


MoveTo(@, titleRect bottom); 
lines 
LineCtitleRect.right,2); 


// Draw the horiz dividing 
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MoveTo(C2,globalStrRect .bottom); 
LineCtitleRect.right,0); 


PenSize(4,4); 
PenPatC&myQD-? gray); 


MoveToCfBTopLef tRect .right, // Draw crosshairs 
fBTopLef tRect .bottom); 
LineToCfBTopRightRect.right,fBTopRightRect .bottom); 


MoveToCfBTopLef tRect .r ight, 
fBTopLeftRect .bottom); 
LineToCfBBotLef tRect .right, fBBotLef tRect .bottom); 


MoveToCfBTopLef tRect .right, 
fBTopLef tRect bottom); 

LineToCfBTopLef tRect. lef t, f BTopLef tRect bottom); 

MoveToCfBTopLef tRect .right, 
fBTopLef tRect .bottom); 

LineToCfBTopLef tRect right, fBTopLef tRect . top); 

PenNormal(); 

) // end drawWindow() 

x 


getQDC) 


This routine returns the pointer used by Quikdrew to 
point to its global deta. 


"asm 
grafSize EQU — $CA 


MOVE.L 0(A52,A0 
SUB.L *grafSize,Ag 


#endasm 
) // end getQdc) 


NumToString() (Package glue routine) 


———————————————————-—-—---— SE ELLE CL 
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NumToS tr ingCtheNum, theStr ing) 


long theNum; 
struct PStr *theString; 
( 

*asm 


MOVE.L D1,A8  ; theString 
MOVE $80,-CSP) ; NumToString selector 
DC.W $A9EE  ; PACK7 

IE 


MousePos.link Listing 
/NoAnimate 
/Output MousePos 
/Type 'DFIL' 'DMOV' 
MousePos 


$ 
MousePos.desk Listing 


File MousePos 

Map MousePos . map 

Name "Mouse Position" 
Open main 

Close close 

Control control 
Status status 

Prime prime 


EventMask 362 
Delay 9 


+ Periodic 
* Control 
* Status 
DeskID 22 


* Test 
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ABC's of C 
Beginning Windows 


Probably the most visible part of the Macintosh user 
interface is the window. Since we can't build much of an 
application without showing something on the screen, we will 
begin to examine how to use the Macintosh Window 
Manager. At the same time, well take a look at the C 
preprocessor, the if-statement, and review the topics from last 
month-the Event Manager, structures, and the case statement. 

Preprocess Your Code 

The C preprocessor provides a variety of useful services. 
We saw last month how to use the #define to provide a 
shorthand name by which to refer to a structure. These ‘define’ 
statements and other data structures can be stored in a seperate 
".h" file and included into our source code at compile time. We 
can create our own new ".h" file to reduce some of C's more 

arcane symbols. We will call this file "abc.h". 

The first three definitions provide some standard 
constants. C has no boolean type, but it is a good idea to use 


/* ebc.h 
x 


* Local definitions to improve readability 
x 


*/ 


"def ine 1 
"gef ine False g 
#def ine Nil Ø 
define and && 
ttdef ine or |i 
“define not ! 
#def ine equals == 
#def ine notequal Iz 


extern char *PtoCstr(); 
extern char *CtoPstr(); 


/* from stdio.h */ 


labeled constants rather than numbers when doing logic. It 
makes the code easier to follow. "Nil" is used with pointers. 
Assign a pointer Nil when you don't want it to point 
anywhere. C guarantees that a pointer can never point to zero, 
so this is a safe initialization value. 

We then have replacements for the logical operation 
symbols. Admittedly, these take longer to type, but they are 
much easier to read (they are especially helpful if you must 
show your code to someone who doesn't use C), and they are 
safer. A very popular C bug is to leave one of the equal signs 
out of the equality operator (see top of next column): 


if Ca = b) 
code; 


instead of 


if (a == b) 
code; 


164 


ts 


C Contributing Editor 
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The first is a perfectly legal C if-statement: it assigns 
the value of b to a, then if a is non-zero, the code is executed. 
The second executes the code only if the value of a equals the 
value of b. The cleverness of this bug is that not only is it 
legal, but many times it is what you want to do. Using 
"equals" instead of "==" makes it much less likely to change 
the meaning of a line by a typo, and it makes it much easier 
to find. 

The last two entries are the Pascal-to-C and C-to-Pascal 
string conversion utilities. These are normally defined in the 
stdio.h file, but since we are not including that file, we can 
put them here. Remember, C and Pascal strings are different, 
so if we send a string to a Toolbox routine, it must be a 
Pascal string. These are the functions that Mac C has. Other 
compilers may have similar functions (Aztec C calls these 
ctop() and ptoc()) or they will do the conversion automatically. 
Check your documentation and place the appropriate functions 
in abc.h so you can use them without repeating the external 
declarations in every source file. 

To use abc.h, just have it as one of the include files at 
the begining of a source file. All the definitions will then be 
available. We may add other definitions later. 

By the way, the May 1986 Byte has an article called 
"Easy C" that describes a considerably expanded set of 
preproccessor definitions. The authors replace many of the 
standard C terms with new ones in an effort to increase 
readability and reduce errors. 

If-then-else 

There are several if-statements in the sample program. 
The if-statement is C's other branching construct. Its general 
form is: 


if Cexpression) 


statement; 

if Cexpression) 
statement; 

else /* shows optional else cleuse */ 
statement; 


If the experession evaluates to a non-zero value, the 
statement is executed. If the expression evaluates to zero and 
an else is present, the statement following the else is executed. 
If no else is present, execution continues after the if. 

If-statements may be nested, but the relation of else to if 
may be ambigous: 


if Cexpression) 
if Canother expression) 
statement; 
else 
Statement; 
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Does the else go with the first if or the second? The 
layout on the page says it will go with the first, but the 
compiler will place it with the second as it is closer. Use 
braces to clear up ambiguities: 


if Cexpression) 


if Canother expression) 
statement; 


else 
statement; 


Structures, Functions, and Pointers 

The only other C issue we need to deal with is how to 
get structures in and out of functions. The original definition 
of C did not allow functions to receive structures as parameters 
or return them (the new ANSI standard does allow this, check 
your compiler). A function could, however, receive or return a 
pointer to a structure. In C a pointer is simply an address, and 
you can get the address of a variable with the address operator 
(the ampersand). In the example, theEvent is an EventRecord 
structure to get the next event from the Event Manager; the 
pointer (or address) to the EventRecord is specified as 
&theEvent: 


GetNextEventCeveryEvent, &theEvent); 


This passes the address of theEvent to GetNextEvent, by 
specifying it as &theEvent. This works well with all C 
compilers, but it does not work in all cases with Toolbox 
functions. The problem is that Pascal allows structures 
(records) to be passed as parameters, as well as by address. On 
the Mac, only structures of four or fewer bytes are passed as 
parameters; longer structures are passed by address. There is 
one structure of four bytes, the Point, which we saw last 
month. Mac C handles this automatically. They define the 
Point as one of the argument types that can be passed to 
Toolbox routines. If you are using Mac C, pass the address of 
the Point. Aztec C, on the other hand, uses a special function, 
pass() to pass points, as shown below: 


FindWindowCpass(Cer where), &whichWindow); /*aztec */ 


Finally, since structures are often used with pointers, C 
has a special operator to access a member of a structure given 
a pointer to the structure. If er is an EventRecord and erp is a 
pointer to an Event Record, the what field is accessed by: 


er .what /* the what member */ 
erp->what /* the what member */ 
(*erp).what /* the what member */ 


The last example shows the indirection operator (the 
asterisk). It yields the value at the address contained in the 
variable. The structure pointer operator (->) is much easier to 
read. 

Putting a Window on the Screen 
The example program this month puts a window on the 
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screen, changes its title, and responds to certain mouse 

commands. The program deals with only one window and 

does not include the change size command as multiple 

windows and changing the size involves accessing the 

Memory Manager. We'll add these features after we cover it. 
The program consists of five routines: 

main() 

Does initialization and calls the main event loop routine. 
InitWindows() must be done if you want to use any of the 
Window Manager routines. See what happens if you do not 
InitCursor(). The dragbounds rectangle limits the range of 
DragWindow(: it ensures the window does not fall off the 
screen. Note that I used the preprocessor to define Screen. 
This was done simply to avoid typing QD- 
>screenBits.bounds. If we find we need to use QD- 
>screenBits.bounds a lot, we can add it to abc.h. 

dowindow() 

The dowindow() routine creates a new window on the 
desktop. As such, it is primarily a call to the toolbox trap 
NewWindow(), which returns a window pointer to the newly 
created window structure. 

There are several potential trouble spots in 
NewWindow(). First, the window record (windowRec) must 
be static. I made it a global. Notice the use of the string 
conversion routines. See what happens if you don't convert 
the string back. The parameter, (WindowPtr)-1, is the behind 
parameter. We wish to place our new window in front of all 
other windows. To do this we must set the pointer to -1. The 
construct (WindowPtr) casts the -1 into the type WindowPtr. 
I expect there would be a serious problem if you left the 
(WindowPtr) out. Try it. Parameter conversion in C is called 
‘casting’. By enclosing a parameter type such as WindowPtr in 
parenthesis, followed by a variable, that variable, in this case, - 
l, is converted into the same parameter type, in this case a 
four byte address. Hence, (WindowPtr)-1 is just a fancy way of 
defining -1 as a long int. Finally, the last parameter is refCon, 
a value passed to the Window Manager for the application's 
own use. I'm just passing a zero because I don't have 
anything to do with it at this time. refCon, though is a long. 
Mac C seems to pass this correctly, but other compilers may 
require the value to be explicitly a long. This is another case 
where things that look correct will not work correctly. To 
make a constant explictly a long, place an "L" after it (OL). 

eventloop() 

This is similar to last month's program. Here the 
EventRecord is local to eventloop(). I only wanted to check 
the keyDown and mouseDown events so I could have changed 
the event mask. You might rewrite it that way. If you are 
reading along in Using the Macintosh Toolbox in C, you will 
notice that they have this program as one function. I try to 
keep things fairly small. 

dokey() 

Here we respond to all the keyDown events. Most of the 
toolbox routines are fairly straight forward. Each window 
function receives a window pointer as a parameter. What we 
are checking for is our menu of command keys. Assuming we 
have a window opened, then our dokey() routine defines the 
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Fig. 1 Program output, window highlited. 


command keys we will respond to: 


Key Function 

cmd m make a window ( call dowindow() ) 
cmdx kill the window (close it) 

cmds show a hidden window 

cmdh hide a shown window 

cmdt change the window's title 

cmdq quit by returning to the finder 


We get the keyboard character by extracting it from the 
message portion of our event record and masking it with a 
mask that guarantees we only get command key sequences. 
Then we extract the ascii value of the key sans command key, 
and check it against the above table of allowed keystrokes. We 
check for the m key first so we can make a new window if one 
does not already exist. After that, our switch construct can list 
each of our key commands knowing that a valid window is 
present. 

domouse() 

domouse handles the mouseDown events. First it must 
determine where the mouse is. The function FindWindow() 
does this and returns a window code and a pointer to the 
relevant window. Note the use of the address operator to pass 
the Point where member. Most of the window functions here 
are straight forward. TrackGoA way() retains control as long as 
the mouse button is down and lights the go-away box if the 
mouse pointer is in it. 

Note that I am always calling DrawGrowlIcon() after each 
Window Manager call. This is not really necessary because 
we're not doing anything with the grow box. Try taking it 
out. 

Final Notes 

We've only touched on part of the Window Manager 
functions. Some will wait until we've covered memory 
management, others until we've covered resources. Placing 
things like window definitions inside resource files helps 
structure the program and makes the user interface components 
easier to modify and port to different languages (human, not 
computer). Since this column is about C, I'm going to avoid 
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using resources so we can use the C functions as much as 
possible. Also, resources present an extra step in getting a 
program to run, and while we're learning how to do things, we 
don't need the extra steps. To learn more about resources, read 
Joel West's "Resource Roundup” series. 

Next month we'll move to menus. Rather than use the 
program in Using the Macintosh Toolbox with C, 1 will add 
menus to this one. Now all we have to do is figure out 
something interesting to put in our windows. Suggestions are 
welcome. 


ABC Window 


/* window manager demonstration 

* base on program in 

* Using Macintosh Toolbox with C 
QUT 16 

x 


/* Here are our include files */ 
*include "abc.h" 


8include "Events.h" 
8include "Window.h" 


/* Our own def ines */ 

/* also includes Macdefs.h */ 

/* also includes Quickdraw.h, which 
in turn requires M68KLIB.D */ 


/* Here are our defines */ 


QD->screenBits.bounds 
0x000000FF 


#def ine Screen 
#def ine charCodeMask 


/* Here are our Global variables */ 


WindowPtr theWindow; 
WindowRecord windowRec; 

Rect dregbound; 
Rect limitRect; 
mainc) 


InitWindowsC); 
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InitCursor(); switch (c) 
FlushEventsCeveryEvent); 


/* Initialize our global variables */ case 'x': 
theWindow = Nil; /*indicates no window */ case 'X': 
SetRect(&dragbound, CloseW indow( theWindow); 
Screen.left + 4, theWindow = Nil; 
Screen.top + 24, break; 
Screen.right - 4, case 's': 
Screen.bottom - 4); case 'S': 
SetRect(&limitRect,60,40, ShowW indow( theWindow); 
Screen.right - Screen.left - 4, DrewGrowIconCtheWindow); 
Screen.bottom - Screen.top - 24); break; 
case 'h': 
dowindowC); /* make new window */ case 'H': 
eventloop(); /* check for events */ HideWindowCtheWindow); 
) break; 
case 't': 
dow indow() cese 'T': 
( title2 = "A Different Title"; 
char *title; /* first title for window */ SetWTitleCtheWindow, CtoPstr(title2)); 
Rect boundsRect ; PtoCstr(title2); 
break; 
if Cnot theWindow) /* if no window exists, make one */ default: 
SysBeep( 1); 
title = "ABC Window"; break; 
SetRect(&boundsRect , 50,598,300, 150); 
theWindow = NewWindow(windowRec, &boundsRect, ) 
CtoPstr(title), True,documentProc, (WindowPtr) -1, True, 9); 
DrawGrowIconCtheWindow); domouse Cer) 
PtoCstr(title); ( EventRecord xer; 
) short windowcode; 
WindowPtr whichWindow; 
event loopC) short ingo; 
( long size; 
EventRecord theEvent ; windowcode = FindWindow(&er-? where, &whichWindow); 
whi leCTrue) Switch Cwindowcode) 
if CGetNextEventCeveryEvent, &theEvent)) ( 
SwitchCtheEvent . what) cese inDesk: 
( if CtheWindow notequal Ø) 
case keyDown: 
dokey(&theEvent); /* check key, */ HiliteWindowCtheWindow, False); 
break; DrawGrowIcon( theWindow); 
case mouseDown: ) 
domouse(&theEvent); /* mouse down evts */ else 
break; ExitToShel1(); /* exit if no window */ 
default: break; 
break; case inMenuBar: 
SysBeep( 1); 
) break; 
dokeyCer ) case inSysWindow: 
EventRecord  *er; SysBeep( 1); 
( break; 
char e /* character from message */ cese inContent: 
char *title2; /* second title for window */ HiliteWindowCwhichWindow, True); 
if CnotCer->modifiers & cmdKey)) DrawGrowIcon( theWindow); 
return; /* only pay attention to cmd keys */ break; 
/* extract character, lower 8 bits */ case inDrag: 
C = er message & charCodeMask; DragWindow(whichWindow, &er-?where,&dragbound); 
if Cc equals 'q' or c equals 'Q') /* 'q' quits program DrawGrowIconCtheWindow); 
*/ break; 
ExitToShel1(); case inGrow: 
if Cnot theWindow) /* not included this month */ 
( break; 
if Cc equals 'm' or c equals 'M') case inGoAway: 
ingo = TreckGoAway(whichWindow, &er-?where); 
dow indow( ); if Cingo) 
return; 
CloseWindow(whichWindow); 
else enone = Nil; 
SysBeep( 1); break; 
return; ) ) 


/* Have a window, so try commands */ 
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C Workshop 


How the Chooser Works with AppleTalk 


Introduction 


The 3.0 and later releases of the Macintosh system 
software (the “System” resource file) contain a new desk 
accessory called the “Chooser.” It replaces the old “Choose 
Printer” and provides a way to select devices in general, not 
just printers (note that the Chooser will not operate with 
earlier System versions) The Chooser is used to select 
remote devices of all sorts including printers and file servers, 
as well as "ports" for local devices such as the serial 
Imagewriter. 

This article covers the operation of the Chooser (and its 
companion, the Namer), and describes how to add support for 
user-supplied devices to the Chooser. It also describes the 
zone concept, an important new addition to the AppleTalk 
architecture. The next release of the Chooser will support 
zone selection for remote (AppleTalk) device lists. Finally, 
the "name" string at the bottom of the Chooser window is 
described. 


Current Device 
(LaserWriter) 


Aiza Lazer 
Tree Eater 
Tim's Very Own 


Bob Denny 
Alisa Systems 
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The icons along the left edge correspond to the device 
files that the Chooser finds on the boot volume. When it is 
first brought up, the Chooser searches the “blessed” (System) 
folder HFS devices, or the entire disk on MFS devices, for 
these device files. For each one it finds, it opens the file, reads 
the icon and flags word, then closes it. When this process 
completes, the Chooser opens the device file for the current 
printer. 

The list box shows the list of choices that are appropriate 
for the type of device that is selected. For the serial Image- 
writer, the icons corresponding to the two possible connection 
ports (printer & modem) are displayed. For the LaserWriter 
and AppleTalk Imagewriter, the names of the available printers 
are listed. Note that you can name a LaserWriter anything you 
want (well, almost), and you must have a unique name for 
each LaserWriter on your net. If you have 5 LaserWriters, 
you'll see their 5 names in the list box. 

The contents and action of the list box is handled by the 
List Manager, a new package supplied in Systems 3.0 and 
later. For more information on 
the List manager, see the updates 
to Inside Macintosh furnished 
with the "December, 1985" (really 
March, 1986) Software 
Supplement. You should also 
refer to Schuster, Mike (1986), 
"Palette Selection via List 
Manager," Mac Tutor,  Vol2, 
No. 5, May, 1986. 

The cells of the list are filled 
in either by default procedures 
contained within the Chooser, or 
via an external fillList procedure 
provided with the device resources. 


STR -4091 
In LaserWriter 
Device Flle 
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For serial printers, the Chooser 
handles the display of the port 
icons in the list window. For 


User name 


The Chooser 


Figure 1 shows the window display of the Chooser that 
was released with System 3.0. Apple is currently finishing 
development of a new Chooser which will have a different 
appearance and will support AppleTalk zone selection, as 
discussed later. 
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Fig. 1 Chooser Display 


AppleTalk devices, a default 
procedure is provided that issues 
periodic name lookups on the net 
for the specified device type and 
fills in the names found (more on 
this in the next section). If the device supports a fillList 
procedure, then it is called by the Chooser to fill in the list 
cells. 

Finally, note that the Chooser is a modeless dialog. This 
means that the Chooser may be active while the user does 
other things. 
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AppleTalk Names and Zones 


AppleTalk supports internetworking, the interconnection 
of networks. Depending on the application mix, a single 
AppleTalk net can comfortably support a cluster of from 4 to, 
say, 20 nodes. Large organizations can connect their work- 
group clusters by means of bridges to form an internet. 


On AppleTalk, entities (such as LaserWriters) are located 
by using the Name Binding Protocol (NBP). Every entity on 
the net has a name which consists of three fields, the object, 
type and zone. The object is the actual "name" of the thing, 
the type puts the thing into a category, and the zone defines 
the set of networks in which the name is known. The first 
two fields are “possessed” by the object, the zone name is 
implicitly set by it's location in the internet, as we'll see. 

NBP locates objects of a given type in the internet by 
broadcasting a request for the names and addresses of all 
objects of that type. The replies come streaming in from all 
over the internet, through the bridges, and into the requesting 
node. Normally a series of requests is issued to reduce the 
vulnerability to lost replies. 

On a large internet, this process can become unwieldy. 
Suppose you had a world-class internet with nets located in 
cities on several continents. You bring up the Chooser to 
select one of your local LaserWriters, and after a minute or so, 
there are 600 LaserWriters in the list! Gad! Imagine the blast 
of traffic that such a lookup would generate. And who cares 
about the LaserWriters in Frankfurt, anyway? 


The solution to this mess is to divide the internet into 
name zones. A zone is defined as a set of nets within which 
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Fig.2 The Namer Utility 
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New Name of LaserWriter 


names are unique. Name lookups are restricted to the nets in a 
single zone. The intent is for organizations to partition the 
internet into zones corresponding to the geographic layout of 
their facilities, or by department, or something like that. 

Note that zone partitioning relates only to name lookups. 
Every node on the internet is addressed by net/node/socket at 
all times. Zones partition the internet into areas in which 
names are known (and must be unique). There may be 
LaserWriters named “Gutenberg” in each zone, but not more 
than one in a given zone. 


Zone Selection 


End nodes can find out what zone they are in and the 
names of all zones in the internet from a local bridge. When 
the new Chooser is started on a node which is connected to an 
internet (at least one bridge on its local net), it asks for its 
zone name, then displays it. It then asks the bridge for a list 
of zones in the internet. If there is more than one name in the 
list, the new Chooser will display a list of zones. From this 
list, the user can select the zone in which subsequent name 
searches will be made. If there are no bridges connected to the 
local net, the new Chooser will hide zone items from the user. 


The Namer 


The Chooser has a companion application called the 
Namer. Its dialog is shown in Figure 2. This program is used 
to change the names of AppleTalk devices (such as 
LaserWriters). It operates in a manner similar to the Chooser, 
except that once a particular device is selected, a dialog appears 
requesting the new name for that device. The user types in the 
new name, then the 
Namer attempts to rename 
it. The device file 
discussed in the next 
section contains resources 
that are used by both the 
Chooser and the Namer. 


The Device File 


Each device which 
uses the chooser is 
represented by a device 
file in the System Folder 
the current startup 
volume. The file's Finder 
"type" (fdType) serves as 
a rough classification for 
the device type, as shown 
in Table 1: (See top of 
next page.) 
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Table 1 — Device File Types 


fdType Device Type 

PRES Serial printer, such as Imagewriter 

PRER Remote printer (any non-serial printer) 

SDEV Serial non-printer device (not supported by current 
Chooser) 

RDEV Remote non-printer device 


The device file has a BNDL resource and associated ICN# 
& FREF resources which serve to give the device its icon as 
seen in the Chooser window (as well as in the Finder, as 
usual). It also contains resources that are used by the Chooser 
to manage the device properly. They include those shown in 
Table 2: 


Table 2 — Device File Resources 


Type ID Use 


STR -4096 If AppleTalk device, its "type" name as 


known on the net via NBP. 


STR  -4095 Singular form of device name as used in 
alerts and dialogs. 

STR -4094 Plural form of device name as used in alerts 
and dialogs. 

STR -4091 The string for the Chooser to put at the top of 
its list window. 

STR# -4093 If AppleTalk PAP device (Printer Acc- 

—4092 ess Protocol, e.g., LaserWriter), the data to 

send in order to rename the device. 

GNRL —4096 If AppleTalk device, NBP retry interval and 
count values for lookup. 

PACK —4096 Code used by non-serial devices for 


handling messages from the Chooser and 
the Namer (see below). 


If the device file contains a PACK -4096 resource, the 
Chooser and the Namer send “messages” to the code contained 
therein to handle the following operations: 


e (fillList) Fill in the list to be selected from 

e (select) An item in the list is selected 

e (deselect) An item in the list is de-selected 

* (getSel) Mark item(s) in the list as currently selected 
* (reName) The user has provided a new name 

* (terminate) Cleanup prior to Chooser or Namer exit 


The format of the PACK resource is shown in Figure 3. 
It starts with a branch around the resource header. The device 
ID is an integer chosen to identify the particular device. Apple 
Developer Support is responsible for assigning these IDs. 
The version word identifies the particular version of the device 
code in the PACK. The code begins at an offset of 10(hex) 
from the physical start of the resource. Note that even though 
it is called a PACK, the Package Manager is never used to 
access the code. 
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Offset 


BRA.S .+$10 


— 4096 


version word 


flags longword 


10 start of PACK's code 


Figure 3 — Chooser PACK Header 


The flags longword in the PACK header is used to 
control the operation of the Chooser and Namer with the 
device. These flags are defined in Table 3. 


Table 3 — Flags Longword Bits 
Bit# Description 


31 Set if device is AppleTalk device 

30 Set if device uses PAP (Printer Access Protocol) 

29 Set if device uses PostScript 

28 Set if device can have multiple instances selected 
simultaneously 

24-27 Set to 0! 

23 Translate international characters to U.S equivalent 


in name 
22 LaserWriter “kludge” flag (don't even ask ...) 
21 Prefix new name with length byte on rename 


16-20 Set to 0! 

15 Set if device accepts fillList message 

14 Set if device accepts getSel message 
13 Set if device accepts select message 

12 Set if device accepts deselect message 
11 Set if device accepts terminate message 
10 Set if device accepts reName message 
0-9  Setto 0! 


The Chooser and Namer call the PACK with the usual 
toolbox Pascal argument convention, and with the arguments 
shown below in C. If your C compiler does not support the 
Pascal function type, you'll need to write a “glue” routine to 
provide the toolbox call frame: 


short pascal device( message, caller, objName, zoneName, 
p1, p2); 


short int message; /* Opcode */ 
short int caller; /* Chooser/Namer or? */ 
char *objName; /* Variable meaning gi 
char *zoneName; /* Zone name for msg */ 
long p1, p2; /* Variable meaning */ 
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The “caller” is 1 if being called by the Chooser, 2 if 


being called by the Namer. The routines should return noErr 
(0) if successful, else some kind of error, Now for the details 


of each of the “calls” that can be made to the PACK, and their 
values: 


fillList (13): 
Caller needs a List Manager list filled in with the choices for 
this device. 


objName not used 
zoneName the AppleTalk zone 
p1 handle to list to be filled in 
p2 not used 
getSel (14): 


Mark the choice(s) that is/are currently selected in the list. 
objName not used 
zoneName the AppleTalk zone 


p1 handle to list 
p2 not used 
select (15): 


A choice has become selected in the Chooser. 

objName if device accepts fillList or is serial device, 
not used; if not, name of object just selected 

zoneName AppleTalk zone in which choice was made 

p1 handle to list 

p2 if device accepts fillList or is serial device, 
row number in list which was selected; if 
not, contains internet address (AddrBlock) 
of AppleTalk device which was selected. 


deselect (16): 
A choice has become deselected in the Chooser. 


objName if device accepts fillList or is serial device, 
not used; if not, name of object just 
deselected 

zoneName AppleTalk zone in which choice was made 

p1 handle to list 

p2 if device accepts fillList or is serial device, 
row number in list which was deselected; if 
not, contains internet address (AddrBlock) of 
AppleTalk device which was deselected. 

reName (18): 


user has provided a new name in the Namer 


objName if device accepts fillList, new name of device 
to be renamed; if not, current name. 

zoneName AppleTalk zone in which choice was made 

p1 if device accepts fillList, list handle; if not, 
pointer to new name string 

p2 if device accepts fillList, row of list to be 
renamed; if not, internet address (AddrBlock) 
of device to be renamed. 


terminate (17): 
a different device icon has been chosen or the Chooser window 
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is being closed and the PACK should clean up if required. 


objName not used 

zoneName the AppleTalk zone (“*” = thisZone) 
p1 handle to list 

p2 not used 


Additional Notes 


The Chooser has internal routines to handle the port 
selection for serial devices and the NBP lookup for "vanilla" 
AppleTalk devices such as the LaserWriter. For serial devices, 
the icons for the modem and printer ports are put into the list 
and displayed. For AppleTalk devices, the STR —4096 string 
is used (along with the currently selected zone name) to do an 
NBP lookup for "=:name @zone". The replies contain the 
names of the various devices of that type, and those names are 
inserted into the list. If the device accepts the fillList message, 
the Chooser calls the PACK to fill the list. 

The Chooser calls the PACK with the getSel message to 
set the "currently selected" item in the list, passing the handle 
to the list. The PACK should, in turn, call the List manager 
(LSetSelect) to select the appropriate cell. The chooser will 
make this call whenever there is a change in the list. For 
example, the Chooser makes this call whenever a new name is 
added to the list during NBP lookup. 

AppleTalk devices are grayed out if AppleTalk is 
disconnected. A warning is displayed if you try to change 
printers in any application except the Finder. 

All printer icons except the currently selected one are 
grayed out unless the current application is the Finder. This 
default behavior is controlled by an application through flag 
bits in the low-memory byte location chooserBits ($946). 
The bit assignments are: 


7 Don't change printer type 
6 Don't change AppleTalk state 
5-0 Reserved (all 1's) 


WARNING -- the above should be touched only by system 
software such as server clients. 


When the user chooses a different device by clicking on a 
different icon, the Chooser calls the old device with the 
terminate message (if accepted), then it does an UpdateResFile 
on the device file followed by a FlushVol on the boot volume. 
Finally, it opens the new device's file. 


The Namer 


The Namer uses some of the device file resources when it 
changes the NBP name of a remote device. Currently, only 
PAP-speaking devices (the LaserWriter) support renaming. 
Future devices such as a file server will also support renaming 
(via their application protocols rather than PAP). 

To rename a PAP device, the Namer first opens a PAP 
connection to the target remote printer. Then it sends the 
strings in the STR# —4093 to the printer until it reaches the 
last string in the list. It then takes the last STR# —4093 
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String, the “new name” string, and the first string from the 
STR# —4092 resource and concatenates them to form a new 
string. It sends this string to the printer, followed by the rest 
of the strings in the STR# —4092 resource. If the printer is a 
PostScript device, it waits for the EOF message from the 
printer. Finally, it takes down the PAP connection. 


An Example: The LaserWriter Device 


Now let's look at the LaserWriter device and see how it is 
handled by the Chooser. First, it is an AppleTalk device 
which does not accept the fillList message. Therefore, the 
Chooser will handle the NBP lookup and list fill process. 

In order for the Chooser to recognize the device, the 
Finder type fdType on the “LaserWriter” file is set to 
'PRER', for a remote printer. A quick look with Fedit or 
ResEdit confirms this. The type and creator are ' PRER' and 
' LWRT ', respectively. 

Inside the Laser Writer file are the various resources needed 
for Chooser use. The GNRL -4096 resource contains the 
NBP lookup retry interval and count, 11 and 5, respectively. 
The interval is in units of 8 ticks, for a total of 88 ticks, or 
about 1.5 seconds. So it makes 5 tries at an interval of 1.5 
seconds, for a total of 7.5 seconds or so. Keep in mind that the 
LaserWriter is "blind" for six seconds during printing. 

The BNDL 128 resource references ICN#s and FREFs for 
4 types of files owned by the creator type LWRT, shown 
below. The PRER icon is the one that shows in the Chooser. 
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Device File 


LaserPrep—a QuickDraw 
interpreter in PostScript 


Laser download font file 


Tl) LWfn Laser download font file 


STR -4096 contains the NBP type name, “LaserWriter”. 
STR -4095 and STR -4094 have the singular and plural 
names for alerts, “LaserWriter” and “LaserWriters.” The STR 
—4091 resource contains “Select a LaserWriter:”, the title 
shown above the Chooser selection box. Your strings should 
end in a colon. 

The STR# -4093 and -4092 resources contain the 
PostScript needed to rename the printer as follows: 


serverdict begin 0 exitserver(clear dict) 
serverdict begin (new name) setprintername end 


where the first line and the second line up through the “(” 
are in the STR# —4093, and the last part of the second line, 
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from the '*)" on, is in the STR# —4092. 

There is a PACK -4096 resource for LaserWriter. The 
device ID is 3 and the version word (for the current release) is 
2. The flags longword is $E0C07000, indicating that Laser- 
Writer is an AppleTalk device that speaks PAP and 
PostScript, that international characters are to be translated in 
its name, that the name must be tested for a bug in the 
LaserWriter code (the “kludge” alluded-to earlier) and that it 
accepts only the getSel, select and deselect messages. 

When the LaserWriter PACK receives the getSel 
message, it selects the printer whose name it recorded in the 
PAPA resource the last time around. When it gets the select 
message, it changes the selected printer in the PAPA resource 
to the new name. Finally, it ignores the deselect message, 
since the new select message overwrites the old PAPA string. 


Other Devices 


Some devices, such as a file server client driver, would 
support selection of several items at a time; this might be a 
set of remote volumes (possibly on different servers) to 
mount. For each selection, the PACK would be called with a 
select message. The PACK would mount the volume, and 
might record the selection in a resource (such as a STR#). 

Remember that the Chooser does an UpdateResFile on 
the device file before deactivating that device (or deactivating 
the Chooser). The next time the system is booted, the device 
could load the STR# resource and automatically mount the 
volumes that were mounted when it was last shut down. 


The Name Field 


The Chooser has an edit text item labeled “user name”. 
The user is supposed to fill his name into this field. 
Currently, only the LaserWriter device uses this field. It uses 
it to inform the printer of the user name of the person who 
owns the current PAP connection to that printer. Other users 
then get a "busy" message with that user's name. The user 
name string is located in the System file as STR —16096, 
indicating that it is “owned” by the AppleTalk .MPP driver 
(ID=9). The chooser changes this resource whenever you 
change the text in its user name field. 


LightSpeed C 


I have taken the position that I will not publish 
benchmarks and reviews of the various C language systems 
available for the Macintosh. In the past, we have published 
articles "using" the Consulair Mac C system, the Megamax 
system and the Aztec (Manx) C system. It has been a while 
since there has been a new introduction in the C arena. We 
developers tend to get into a rut, so I feel this newcomer 
deserves a few paragraphs. 

I recently received an evaluation copy of the LightSpeed 
C system (V1.02) from Think Technologies. There is a lot of 
folklore circulating about these days regarding LightSpeed C. 
Here are my subjective impressions. 
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The compiler and linker are surprisingly fast, reducing 
development turnaround time significantly. The generated 
code is reasonably good, comparable to the other systems I 
have used. I shouldn't even have to say it, but the linker does 
selectively load from libraries. Desk accessory and driver 
support is built-in, as is “pascal” calling convention. You can 
also make a “code resource” with arbitrary type such as PACK 
or INIT or whatever. 

The built-in editor has a multi-file “grep” search and 
replace that I particularly appreciate. My company marketed 
an editor for the PDP-11 for years that had this feature, and our 
customers loved it. It (mostly) eliminates the need for editor 
macros. Also, the linker can put symbolic info into the 
application for use by Macsbug or TMON. The combination 
of LightSpeed C & TMON with the extended user area is 
about as powerful a development environment as you'll find 
on a micro. 

On the minus side, Lightspeed has no assembler support 
(Think says it's coming). Their Pascal call and driver support 
does eliminate a lot of need for an assembler. You can use the 
MDS assembler then run the REL file through a LightSpeed 
utility to make it a library. It will not convert “resource” 
REL files, though, so you can't use their linker to make 
FKEYs or INITs from assembler. 

Everything built by LightSpeed C has a 400+ byte 
“preamble” attached to the front. It consists of a collection of 
small routines that handle switch statement dispatches, long- 
word multiplies and divides, and that sort of thing. They 
should have been library modules. It makes it impractical to 
write FKEYs, INITs or small drivers in C, my favorite 
pastime with Consulair. 

One “feature” I particularly dislike is the choice of 16-bit 
INT's. While this follows the Lisa Pascal convention, it 
violates the C convention of choosing INT to be the “natural” 
word size of the machine. Last time I looked, the 68000 
family was a 32-bit machine, capable of adding 32-bit 
numbers in a single leap. Think's reasoning was that the bus 
is only 16-bits wide, therefore 16-bit INTs are faster. A 
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hardware quirk. Wait till 2 years from now. In any case, it 
makes it a pain to convert programs over to LightSpeed from 
other C languages. 

If you plan to use the List Manager with LightSpeed, be 
aware that the List Manager is not supported in the 
"MacTraps" glue library. There is an undocumented hook that 
makes it possible to define calls as traps in a general way. It 
goes like this: 


pascal void RomCallC) = @xA9ZZ; 


where the “void” can be replaced with a function return type. 
The resulting defined function can take parameters like any 
other. It's highly non-portable, but so is Macintosh code. 


Final Words 


It's nice to be back writing for Mac Tutor. I have been 
incredibly busy for the past 5 months, managing a growing 
business and working with Apple Computer to put AppleTalk 
on VAX/VMS. That project is mostly completed now, so the 
fun part is starting ... doing the network applications. 

AppleTalk, and the Mac as a whole, is going to undergo 
an explosive expansion during the next year or so. There are a 
host of "new" computer systems techniques that may show up 
in the Macintosh architecture, such as hardware memory 
management, system-driven task scheduling, multi-tasking 
and supercharging for QuickDraw. If you want some hints, re- 
read that innocuous “developer's questionnaire" that appeared in 
one of the Software Supplements in the Fall of 1985. 
Remember that? It asked questions like “Do you directly 
access the low memory globals?” 

Next month's C Workshop will cover AppleTalk inter- 
networking in more detail, including bridge operation, the new 
Zone Information Protocol, and will include a real C program. 
Unul then. toa 


Cte n, 
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ABC's of C 


Menus and Windows in LightSpeed C 


An easy to follow user interface is one component of 
good quality software. On the Macintosh, the design of the 
user interface is largely laid out for us. Use windows and 
menus. Last month, we used control keys to place a single 
window on the screen and make some modifications to it. 
This month we will do the same thing but use menus rather 
than control keys. You will notice that this month's program 
is very similar to last month's. There are some obvious 
differences from the addition of menus and some less obvious 
differences because I used a different compiler. Since the 
program contains functions from last month, we'll tie up a 
few loose ends, and cover a basic C concept as well. 


C Assignment Statements 


The assignment statement is probably the most basic 
statement in most languages. I don't think I've used it yet in 
any of these programs because we have done very little 
arithmetic. Since it is so basic, we'll go over it this month. 


The C assignment operator is the equal sign: 
T . 


4 
a + b; 
max(x,y); 


x 
y 
z 


The effect of the assignment operator is to take the value 
of the right hand side and place in the variable on the left hand 
side. 


With most languages, this would be about as much as we 
would say. C, however, also offers a set of specialized 
assignment operators. These apply when the variable on the 
left is also on the right as in: 


x=x+ l; /* increment x by 1 */ 
The preferred C form is: 
x+ 1; /* increment x by 1 */ 


This is a bit easier to follow as it is obvious that what 
we want to do is increment x. It would also be obvious to the 
compiler, which may generate more efficient code. 


Here is a list of all the C assignment operators. 


assignment 

addition assignment 
subtraction assignment 
multiplication assignment 


+ 


» 
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division assignment 
modulus essignment 
shift right assignment 
shift left assignment 
bitwise AND assignment 
bitwise inclusive OR 
bitwise exclusive OR 


P o— 8S9 av an 
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The first three are the most frequently used, but you may 
run across another. Don't be too surprised when you see one. 


Cleaning Up the Windows 


There is one point from last months program about 
windows that deserve some clarification: The use of the "cast" 
in the call to NewWindow(). Each parameter of a function has 
to receive the correct type. C does not do type checking on 
external functions, and passing the wrong type can yield 
disastrous results. NewWindow() expects a WindowPtr for its 
behind parameter (specifies an existing window to place the 
new window behind). If the new window should be in front of 
all the other windows behind receives a minus one, but the 
minus one must be a window pointer. 


To change the type of an object a cast is used. Place the 
type name in parentheses before the object you wish to 
change. The effect is as if there were a new variable of the 
proper type to which you assigned the orignal object. The 
original object is unchanged. It is preferrable to use a cast 
rather than an integer or long because the internal 
representation of an integer or long may not be the same as 
that of a pointer. So, to change minus one to a WindowPtr, 
do: 


(WindowPtr2-1 


This will ensure that the parameter is not only of the 
same size, but of the correct type as well. 


LightspeedC 


Since this column is devoted to learning to program in C 
on the Macintosh, I have been on the lookout for tools that 
will facilitate the learning process. LightspeedC is such a 
tool. Its major advantages from our point of view is that it is 
very fast at compiling and linking and that it places you at the 
correct position in your source file if the compiler detects an 
error. The result is that you can edit, compile, link, and run 
your program very rapidly, make small variations in the code 
and determine their effect, and generally have the opportunity 
to make more mistakes in a shorter period of time. If we learn 
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from our mistakes, Lightspeed C is a useful tool for learning 
C on the Macintosh. 


LightspeedC is different from the other available C 
compilers as it does not use a Unix-like setting [Yea! -Ed.] - 
nor does it use separate programs in the Macintosh window 
environment. Instead it creates its own enviornment (that 
follows the Macintosh User Interface) from which all editing, 
compiling, linking, and running take place. The integrated 
editor is roughly similar to the Edit application. Menus 
available from inside the editor allow you to run, compile, or 
just check the syntax. As soon as the compiler detects an 
error, you are returned to the editor with the cursor at the 
location the compiler found the error. In other words, you get 
one error at a time. 


The link operation is extremely fast. With this month's 
small program, I often did not notice the link had happened. If 
you choose the run option from the editor, it will compile, 
link, and launch your program. When you quit your program, 
the LightspeedC environment reloads, and you can continue. 


The key to the speed seems to be the system's use of a 
project. The necessary files are installed into the project, and I 
guess much of the linking takes place at intallation or compile 
time. The project also provides a make facility—it keeps track 
of changes in source, include, and library files, and recompiles 
them as necessary. 


I came across a few problems in using LightspeedC. 
First, it follows the proposed ANSI standard for passing 
structures as parameters. As I mentioned last month, C 
traditionally only allowed passing pointers to structures and 
this complicates the passing of the Macintosh Point type 
(which is a four byte structure that the Mac expects to find 
passed by value rather than by reference). LightspeedC passes 
a Point correctly by value. This is not a problem except it 
took me over an hour to realize what was going on. I wrote 
the menu program under Mac C first, and then installed the 
source in Lightspeed. 


A second problem is that Lightspeed does not include the 
QD variable we used last month to obtain the size of the 
screen. You will note in this month's program that the 
dragbound rectangle (which describes the limits for dragging a 
window) and the limit rectangle (which set the maximum size 
to which a window may grow) are set with hard coded 
numbers. 


A more serious problem is that there is no way to easily 
print to the screen in the Macintosh environment. 
(LightspeedC includes printf() as well as a number of other 
Unix-type output functions, but the use of any of these 
invokes a Unix environment that eliminates the menu bar and 
windows. Since I was trying to debug a problem with 
windows, this was not at all useful. By the way, LightspeedC 
includes one of the larger collection of Unix compatible 
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functions in its libraries.) Not having a printf() like routine 
for the Mac environment considerably reduces the usefulness 
of LightspeedC as a learning tool. [Too bad. They could use 
an assembler too! -Ed.] 


The manual that comes with the package is a large format 
paperback. About a third of its pages are devoted to a 
description of all the Unix compatible functions. (Many of 
these, such as the string functions, are useful in the Macintosh 
environment. Whether such things as the memory 
management and file handling routines are useful would depend 
on whether they invoke the Unix environment and whether 
you wish to port your program off the Macintosh. The 
descriptions of the Macintosh functions are limited to listing 
the name and calling sequence in the order they appear in 
Inside Macintosh. Alphabetical order would have been better. 
[Why is it developers keep slighting the Mac toolbox in their 
documentation? -Ed.] 


Finally, Lightspeed uses different names for its header 
files There is no standard so this is not a problem. Since I 
moved the code to Lightspeed from Mac C, it would not 
compile immediately. I decided to change the names of the 
header files so they would look familiar to most people. 


In general I am very impressed with the package as a 
learning environment. The fact that it generates fast, compact 
code (a fact I have not verified) is simply a bonus. 


C What's on the Menu 


This program does the same thing last month's program 
did except it's control is through menus. There is one 
additional visible (to the user) feature: an item in the File 
menu will add a new menu called Test. The Test menu allows 
items to be checked. The comments in the code describe other 
differences. I'll describe each function briefly. 


main() 

Main has basically disappeared. It simply calls two 
initialization functions. I prefer to keep the system 
initialization separate from the application. Eventually we'll 
have everything we need in the system application and will 
not have to change it. 


Initsys() 

Initializes system stuff. If you compare the initialization 
this month with last month's, you will notice the first two 
lines were not in last time. They are handled automatically by 
Mac C. 


Initapp() 

Sets up the menus. AppendMenu() adds the menu 
string(s) to the menu; InserMenu() adds the menu to the menu 
bar. Notice the string in the calls to AppendMenu(). It 
contains several metacharacters as Inside Macintosh calls 
them. They control the display and sometimes the operation 
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of the menu items. 
Meta Characters Explained 


Character Meaning 


Separates items (can also use return) 
Item has an icon; followed by icon number 
Item is marked with following character 
Item is in special style, 
followed by 8, I, U, 0, or S 
/ Item has keyboard equivalent, followed by the 
character 
( Item is disabled 


~ c pw. 


eventloop() 

An event loop like we have seen before. The test on 
theWindow at the begining enables/disables the items in the 
File menu to open/close the window. The disabled items are 
in gray. We probably should disable the Apple menu because 
we don't support Desk Accessories. Other items in other 
menus Should switch as well. You might try to add these 
features. 


Notice the special handling of keyDown events. In case 
of keyDown, the modifers field is checked for the command 
key being down. If the command key is down, MenuKey( is 
used to generate the same code as MenuSelect(), and the code 
is passed to domenu(). This is how command keys work with 
menus. You might want to add some more command keys to 
the menus. 


domouse() 

This is almost identical to last month's. The only 
difference is that here we call domenu() if the mouse is in the 
menu bar. Remember to handle er->where correctly for your 
compiler. 


domenu() 

This is simply a switch. The menu code consists of two 
components packed into a long. HiWord() and LoWord() are 
two Toolbox functions that extract the lower and upper words 
of a long. 


dofile() 

Contains the code to handle the File menu. Note cases 
five and six. They contain a call to DrawMenuBar() because 
they change the menu bar. Any changes do not appear until 
the menu bar is redrawn. 


dowind() 
Handles the Window menu. Add Disableltem() and 
Enableltem( calls to this one. 


dotest() 
This does not do anything except mark and unmark the 
items. 


The Program 
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/* menu and window manager demonstration 
* base on program in 

* Using Macintosh Toolbox with C 

* page 91 


»* »* * »* x x MH 


— 


ttinclude 
ttinclude 
tt'include 
include 


Compiled with LightspeedC 


Important note for Mac C users: 


Everyplace you see event-)where, 
replace it with &event-^ where 


"abc.h" /* our own header, see last month */ 
"Events.h" 

"Window.h" 

"Menu .h" 


/* defines for menu ID's */ 


“define 
“define 
define 
"define 
"def ine 


Mdesk 100 
Mfile 101 
Medit 192 
Mwind 103 
Mtest 104 


/* Global variables */ 


MenuHandle menuDesk; /* menu handles */ 

MenuHandle menuF ile; 

MenuHandle nenuEdit; 

MenuHandle nenuWind; 

MenuHandle nenuTest; 

WindowPtr theWindow; 

WindowRecord windowRec; 

Rect dragbound; 

Rect limitRect; 

main() 

initsys(); /* system initialization */ 
initappC); /* application initialization */ 
eventloop();  /* Do it! */ 


/* system 
x 


x 

x 

x 

*/ 
PARS 


initialization 

note use of hard coded screen sizes 
with LightspeedC. This will work 
with other compilers but is not 
good practice 


InitGraf (&thePort?; /* these two lines done */ 
InitFonts(); /* automatically by Mac C */ 
InitWindows( ); 

InitCursor(); 

InitMenusC); 

theWindow = Nil; /*indicates no window */ 
SetRect(&dragbound, 9, 8,512,342); 
SetRect(&limitRect, 60, 40,588,318); 


— 
32€ 2 w HM MH »* 9 o» * 


— 


application initialization 


Sets up menus. 

Each menu is a separate group 

of lines. Note the last menu 

is appended but not inserted. This 
makes it part of the menu list but 
not in the menu ber. 
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int tappC) 


menuDesk = NewMenu(Mdesk ,CtoPstr("\24")); 
AddResMenu (menuDesk, ' DRVR' ); 
Inser tMenu (menuDesk, 8); 


nenuFile = NewMenu(Mf ile, CtoPstr("File")); 
AppendMenu (menuF ile, 

CtoPstrC "Open Window/M; Close Window/X;Quit/Q")); 
AppendMenu (menuF ile, 

CtoPstr(C"C- ;Show Test; (Hide Test")); 
Inser tMenu (menuF ile, 9); 


menuEdit = NewMenu(Medit, CtoPstr(' Edit"); 
AppendMenu (menuEdit, 

CtoPstrC"Undo; (-; Cut; Copy;Paste;Clear”)); 
Inser tMenu (menuEdit, 9); 


menuWind = NewMenu(Mwind, CtoPstr(C"Window" )); 
AppendMenu (menuWind, 

CtoPstr(C "Hide; Show; New Title")); 
Inser tMenu (menu ind, 0); 


menuTest = NewMenu(Mtest, CtoPstr("Test")); 
AppendMenu (menuTest, 
CtoPstrC"Pick; One; JOf; These" )); 


) DrawMenuBar( ); 
/* Event Loop 
x Loop forever until Quit 
Ef 
i d 
EventRecord theEvent; 
char e 
short windowcode; 
WindowPtr WW; 
whileCTrue) 
if CtheWindow) /* this code is here to */ 
( /* prevent closing an */ 
EnableItem(menuFile,2); /* a closed window */ 
DianblelteaCreruF ile, D; 
else 
( 
EnableItemCmenuF ile, 1); 
DisableI tem(menuF ile, 2); 
if CGetNextEventCeveryEvent, &theEvent)) 
SwitchCtheEvent . what) 
( /* only check key and */ 
case keyDown: /* mouse down events */ 
if j sen & cmdKey) 
= theEvent.message & charCodeMask; 
oen enu e c2». 
break; 
case mouseDown: 
domouse(&theEvent); 
break; 
default: 
break; 
) 
) 
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/* domouse 

x handle mouse down events 
x/ 

domouseCer ) 

EventRecord *er; 


short windowcode; 
WindowPtr whichWindow; 
short ingo; 

long size; 


windowcode = FindWindowCer-»where, 


&whichWindow); 


uii (windowcode) 


cese inDesk: 
if CtheWindow notequal 0) 


HiliteWindowCtheWindow, False); 
DrewGrowIcon(theWindow); 


break; 

case inMenuBar: 
domenuCMenuSelectCer-? where )); 
break; 

case inSysW indow: 
SysBeep( 1); 
break; 

case inContent: 
Hil i teWindowCwhichWindow, True); 
DrawGrowIcon(CtheWindow); 
break; 

case inDrag: 
DragWindowCwhichWindow, 


er-? where, &dragbound); 


DrawGrowIconCtheWindow); 
break; 

case inGrow: 
/* not included this month */ 
break; 

case inGoAway: 


ingo = TrackGoAwayCwhichWindow, er-?where?); 


if Cingo) 
( 


CloseWindowCwhichWindow); 
ue Nil; 


break ; 
) 


/* domenu 
x handles menu activity 
* simply a dispatcher for each 
x menu. 
*/ 
domenu(mc) 
long mc; /* menu result */ 
short 
short 


menuId; 
menuitem; 


menuld = HiWord(mc); 
menuitem = LoWord(mc); 


PNE Cmenuld) 


case Mdesk : break; 
/* not handling DA's */ 
cese Mfile : dofileCmenui tem); 
break; 
case Medit : break; 
case Mwind : dowind(menuitem); 
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break; 
case Mtest : dotest(menuitem); 


) break; 
HiliteMenuC0); 
/* dofile 
x handles file menu 
x 
dof ileCitem) 
short item; 
char *titlel; /* first title for window 
*/ 
Rect boundsRect; 


uis (item) 


cese 1 : /* open the window */ 
title1 = "ABC Window"; 
SetRect(&boundsRect , 50,590,300, 158); 
theWindow = NewWindowC&windowRec, 
&boundsRect,CtoPstr(title1), True, 
documentProc, (WindowPtr) -1, True, 8); 
DrewGrowIcon(theWindow); 
PtoCstr(titlel); 
DisableItemCmenuF ile, 1); 
EnableItemCmenuF ile, 2); 
break; 


case 2 : /* close the window */ 
CloseW indow( theWindow); 
theWindow = Nil; 
Disablel tem(menuF ile, 2); 
EnebleItemCmenuF ile, 1); 


break; 
case 3 : /* Quit */ 
ExitToShe11C); 
break; 
case 5 : /* Install additional menu */ 


InsertMenuCmenuTest , 0); 
EnableItemCmenuF i1e,6); 
DisebleItem(nenuFile,5); 
DrewMenuBar(); 

break; 


case 6 : /* remove additional menu */ 
DeleteMenu(Mtest); 
Enablel ten(menuF ile 9; 
Disableltem(menuFile,6); 
DrawMenuBar (); 
break; 
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% 2 »* »* »* » * 
~~ 


dowind 
handles window menu 
Note that each case contains an 
if testing the existance of the 
window. This could be written 
with one if before the switch. 
x 
dow indC item) 
short item; 


char *title2; /* second title for window */ 


TENE Citem) 


case 1: /* Hide */ 
if CtheWindow) 
HideWindowCtheWindow); 
break; 
case 2 : /* Show */ 
if CtheWindow) 
ShowW indowCtheWindow); 
break; 
cese 3 : /* Chenge title */ 
if CtheWindow) 


title2 = "A Different Title": 
SetNTitleCtheWindow, CtoPstr(title2)); 
PtoCstr(title2); 


break; 


) 


/*  dotest 
x Handles new menu. 

x All this does is mark menu 

x items if they are not marked and 
*  unmark them if they are. 


*/ 
dotestCitem) 
short item; 
short mark; 


Get I temMark(menuTest, item, &mark); 
if (mark) 

CheckI tem(menuTest, item, False); 
else 


CheckI temCmenuTest, item, True); 
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Networking 


A PostScript Driver in LightSpeed C 


[This article by Bob Denny, a distinguished member of the 
MacTutor Editorial Board of Directors, presents a driver that 
allows simple writeln statements from a high level language 
to output directly to a LaserWriter in Postscript over 
AppleTalk, which makes the laser a quick and convenient 
printer device the same way you might use an ImageWriter! 
To do this, we "steal" Apple's code from the LaserWriter file 
that already knows how to talk to the Laser and simply 
provide a machine language interface to it. Then we write a 
device driver in LightSpeed C, and finally, our Pascal 
application can simply open the driver and print to it. An 
example of how to open and write to a device driver is given 
in MacPascal and TML Pascal. F inally, calling drivers is 
explained by presenting examples using standard file I/O, the 
high level device manager calls, and the low level device 
manager calls. This article is a significant contribution to both 
device drivers in general, and the LaserWriter in particular. 
Thank you , Bob! -Ed.] 


A PAP Driver for the LaserWriter 


Alan Wootton played a dirty trick on me for my birthday 
last month. He bought me a copy of SmallTalk-80 for the 
Macintosh. I had made some comment about being interested 
in it, trying to learn about it from the Addison-Wesley books 
(and failing miserably), and just getting a Mac+ so I could run 
it, etc. Well, I ended up getting totally sucked in. 

I soon became frustrated at my inability to print to our 
LaserWriter from SmallTalk-80. I wanted to catalog the 
message protocols for some of the most common classes 
( numbers", for instance). I thought, “Here is a reason to 
learn SmallTalk-80 and PostScript all at once!" Alan knows 
how my mind works, because he called me up moaning about 
not being able to print to his LaserWriter. That did it. My 
aging brain needed a good workout, so ... 

It seemed hopeless to try to interface to the Print Manager 
from SmallTalk-80. Rather, I decided to build a driver which 
would support direct communication with the LaserWriter via 
the Appletalk Printer Access Protocol (PAP). Once the driver 
was done, I could then go into SmallTalk-80 and modify it to 
print using PostScript. The Mac implementation of 
SmallTalk-80 has an interface to the device manager and it 
could be used to send PostScript to the “chosen” LaserWriter 
via the driver. In fact the driver could be used from other 
interpretive languages such as MS Basic or MacPascal. 

This article reviews the PAP manager, including an 
enhancement in the newest version, and describes the "PAP 
Driver" along with an example using Mac Pascal. It does not 
describe PAP itself (that will be the subject of a future article). 
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The PAP Manager Revisited 


Refer to the "Laser Print DA for Postscript" by Mike 
Schuster, in the March 1986 issue of Mac Tutor. In that 
article, Mike describes the PAP manager and how to build a 
desk accessory that will transmit the contents of a file to the 
LaserWriter. 

PAP, or Printer Access Protocol, is a combined 
application and session level protocol which is used to 
communicate with the LaserWriter over Appletalk. It uses 
ATP (Appletalk Transaction Protocol) for error and flow 
control. 

On the Macintosh, PAP is implemented in a “code” 
resource, not as a driver. The original Inside LaserWriter 
describes an interface to PAP that was apparently never 
released. Last year, Bill Parkhurst and Mike Schuster dove 
into the “LaserWriter” resource file and found that the PDEF- 
10 resource contains the code that handles PAP communt 
cations, the PAP Manager. It tumed out that the interfaces to 
the routines in the PAP Manager look just like those described 
in Inside LaserWriter, except that the routines are vectored 
through a list of jumps at the beginning of the code resource. 

The interface is quite straightforward. There are basic calls 
for "open", "close", "read" and "write". These functions 
operate in the context of a session, a private connection 
between the client (Mac) and the server (LaserWriter) that may 
last for the duration of several jobs. 

There is a "status" call that generates a one-shot status 
request to the server, to which the server responds with a 
human-readable status string. The status request may be 
issued by any client that can see the server. It does not operate 
within a session. The status call makes it possible to check 
the status of the LaserWriter whether or not it is busy 
processing a job for someone else. 

Finally, there is an “unload” call, which must be issued 
when an application is finished using the PAP manager. If 
the application releases the memory occupied by the PAP 
manager without making the unload call, internal PAP 
manager timers will go off and cause a jump into garbage. 


The PAP Manager Interface & Operation 


The name of the current (chosen) printer resource file 
(e.g., “LaserWriter”, “ImageWriter” or whatever) is contained 
in the System file as STR resource number -8192. If this 
String contains "LaserWriter", then the workstation is 
currently set to print to a LaserWriter. Which one? 

The Appletalk "entity" name of the currently chosen 
LaserWriter is contained in the PAPA resource number -8 192, 
which is located in the LaserWriter resource file. This file is 
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located in the System Folder (the “blessed” folder on HFS 
volumes). The format of the PAPA resource is exactly that 
needed for the Name Binding Protocol (NBP) to locate the 
selected LaserWriter. The chooser changes this resource 
whenever the chosen printer is changed. 

Strictly speaking, the previous two paragraphs contain a 
white lie. The “LaserWriter” resource file might have been 
renamed something else, or there may be several versions of 
the LaserWriter resource file present on the system, each with 
a unique name. The STR -8192 resource in the System file 
always contains the name of ‘the currently chosen printer 
resource file. 

Just because the currently chosen printer name isn't 
*LaserWriter" doesn't mean that it's not a LaserWriter resource. 
Refer to Denny, Bob (1986), “How the Chooser Works", Mac 
Tutor, Vol. 2, No. 7, July, 1986. You might want to look at 
the STR -4096 resource in the device resource file. This 
string contains the NBP “type” of the printer. If it contains 
“LaserWriter” then it's a good bet that the device is indeed a 
LaserWriter. For the purposes of this article, we assume that 
the resource file is named “LaserWriter” and that it is located 
in the System folder. 

Once you have located the LaserWriter resource file, you 
have access to the PAP Manager. The PAP manager is a code 
resource, specifically PDEF resource number 10 in the 
LaserWriter resource file. It begins with a fixed sequence of 
jump instructions to the actual routines: 


Offset Code 
9: JMP PAPOpen 
4: JMP PAPRead 
8: JMP PAPWrite 
12: JMP PAPStatus 
16: JMP PAPClose 
20: JMP PAPUnloead 


Each of the routines takes its parameters in the Toolbox 
(Lisa Pascal) format. Most execute asynchronously and use a 
specified memory location to post the status of the operation. 
Before using the PAP Manager, your program must locate the 
PDEF-10 resource, then load and lock it. 

You must write an assembler “glue” module to handle call 
and return through the jump table. If your compiler doesnt 
support native Macintosh toolbox parameter passing, the glue 
routines must also re-arrange the parameters according to the 
Pascal conventions. The individual routine interfaces are 
described below in C (neglecting the jump-table operation). 


PAPOpen: 


This call is used to open a connection, or session, to a 
particular LaserWriter. The key to the connection is the 
reference number (refNum) returned by the call. The process is 
asynchronous and will complete when the connection is 
opened or if the specified printer cannot be located. If 
someone else has a.connection open to the printer, the 
PAPOpen will perform retries for a “long” time, after which it 
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will return an error. You may then re-issue the open call and 
try again. 


struct statusBuf 


long int papStuff; 
char stetusStr ing[255]; 


4 


pascal short PAPOpen(refNum, 
printerName, flowQuantum, 
statusBuff, compState) 
short *refNum; 

char *printerName; 

short flowQuantum; 

struct papStatus *statusBuf ; 
short *compState; 


refNum is the reference number of the PAP connection, 
returned after the connection has been opened. 

printerName is the NBP entity name for the printer 
(usually the contents of the PAPA -8192 resource). 

flowQuantum indicates the maximum size message that 
your end can receive from the LaserWriter, in multiples of 512 
bytes. For example, if your receive buffer is 1024 bytes in 
size, specify flowQuantum = 1024/512 = 2. The LaserWriter 
can accept messages up to 4096 bytes; its flow quantum is 8. 
You should use as large a flow quantum as possible so as to 
reduce ATP overhead. 

statusBuf points to a PAP status buffer as defined above. 
During the connection opening process, the PAP manager 
places status messages from the LaserWriter into the 
statusString field asynchronously. Your application might 
display the status string contents once a second or so during 
the connection opening phase. If someone else's job is being 
processed, the LaserWriter will put descriptive information 
about that job in the status return. The statusString should be 
initialized with a zero byte in the first character before calling 
PAPOpen. 

compState is the address of a 16-bit word that is used to 
indicate the progress of the (asynchronous) connection 
opening. If the PAPOpen call returns with status noErr (=0), 
then the word pointed to by compState will contain a number 
greater than zero, indicating that the opening phase is in 
progress. When the connection has been opened, this value 
will change to zero (no error). If the open fails, *compState 
will contain a negative value (indicating an error). 


PAPRead: 


This call is used to read data from the LaserWriter. The 
operation is done asynchronously. Normally, during a printing 
session, the LaserWriter will not send anything back to the 
workstation. If there is an error condition, such as paper out or 
a paper jam, the printer will try to send a status message back 
to the workstation. In that case, if your application has not 
issued a PAPRead, the printer will hang. Also, if you send 
PostScript to the printer that causes data to be sent back to the 
workstation, you must read that data or the printer will hang. 


pascal short PAPRead(refNum, buffer, 
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length, eof, compState); 
short refNum; 
char *buffer; 
short *length; 
short *eof; 
short *compState; 


refNum is the reference number of the connection, returned 
from the PAPOpen call. 

buffer is the address of a buffer to receive the data from the 
server (LaserWriter). Note that the buffer must be large 
enough to handle messages as large as you specified in the 
flowQuantum parameter to the PAPOpen call. 

length is the address of a word that will be filled in with 
the length of the data actually received (bytes) when the read 
completes. 

eof is the address of a word that is used to detect an end-of- 
file signal from the PostScript interpreter in the LaserWriter. 
When the read completes, if the word addressed by eof is non- 
Zero, the PostScript interpreter in the LaserWriter has sent an 
end-of-file indication to the workstation. The LaserWriter 
sends this in response to a previous end-of-file sent to it by 
the workstation, completing a handshake. This means that 
your application must have a PAPRead outstanding at the 
completion of a job, so that the LaserWriter can return its end- 
of-file. See the PAPWrite description. 

compState is the address of a 16-bit word that is used to 
indicate the progress of the (asynchronous) read operation. If 
the PAPRead call returns with status noErr (=0), then the word 
pointed to by compState will contain a number greater than 
zero, indicating that the read is in progress. When the 
LaserWriter sends a message to the workstation, this value 
will change to zero (no error). If the connection has broken, 
*compState will contain a negative value (indicating an error). 


PAPWrite: 


This call is used to send data to the LaserWriter. The 
Stream of PostScript sent to the LaserWriter may be buffered 
into messages as long as 4096 bytes (the LaserWriter's flow 
quantum). Your application should attempt to buffer the 
PostScript as much as possible, as this reduces the network 
overhead dramatically. This will be especially true when 
Appletalk internetworks include links using public packet- 
Switching nets (such as Telenet or TYMnet). These nets have 
large propagation delays, and the transaction nature of PAP 
makes it extremely sensitive to message size. 

Just cram the PostScript into the buffer till it's full, then 
issue the write. Since PAPWrite is asynchronous, you could 
double-buffer the write stream, filling one buffer while the 
PAPWrite is outstanding on the other buffer. In any case, at 
the end of the job, set the eof flag (see below) and issue the 
final PAPWrite on the partial buffer remaining. 


pascal short PAPWriteCrefNum, buffer, 
length, eof, compState); 
short refNum; 
char *buffer; 
short *length; 
short *eof; 
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short *compState; 


refNum is the reference number of the connection, returned 
from the PAPOpen call. 

buffer is the address of a buffer containing the data to be 
sent to the server (LaserWriter). This buffer may be up to 
4096 bytes in length, per the LaserWriter's flow quantum. 
You'll get an error if the receiver's flow quantum is exceeded. 

length is a word containing the number of bytes to be sent 
in the message. 

eof is a word that is used to signal end-of-file to the 
PostScript interpreter in the LaserWriter. This should be done 
at the end of the print job, on the last message of the job. If 
the LaserWriter detects a PostScript error during a job, it will 
ignore input until it detects end-of-file in the stream. At that 
point is will send an end-of-file back to the Workstation, reset 
its state to the permanent defaults, then assume that further 
data belongs to a new job. 

compState is the address of a 16-bit word that is used to 
indicate the progress of the (asynchronous) read operation. If 
the PAPWrite call returns with status noErr (20), then the 
word pointed to by compState will contain a number greater 
than zero, indicating that the write is in progress. When the 
LaserWriter has successfully received the message, this value 
will change to zero (no error). If the connection has broken, 
*compState will contain a negative value (indicating an error). 


PAPClose: 


This function closes the PAP connection to the 
LaserWriter. This should only be done after the exchange of 
end-of-file messages as already outlined. The function is 
executed synchronously, and it cancels any outstanding 
PAPRead and/or PAPWrite calls. 


pascal short PAPClose(refNum, buffer, 
length, eof, compState); 
short refNum; 


refNum is the reference number of the connection, returned 
from the PAPOpen call. 


PAPStatus: 


This function operates outside the context of a PAP 
connection. No PAP connection need be open to obtain status 
from a server (LaserWriter). It executes synchronously, and it 
returns a status string from the server. This function is used 
by the Macintosh print manager to generate the messages that 
appear in the status window during a LaserWriter print job 
(except in the case of a PostScript error, when the status is 
sent via the PAP connection from the LaserWriter to the 
workstation). 


sia statusBuf 
long int papStuff; 
char statusStr ing[255]; 
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or addrB lock 


short net; 
char node; 
cher socket; 


) 


pascal short PAPstatus(printerName, 
statusBuff , netAddr) 

cher *printerName; 

struct papStatus *statusBuf ; 
struct eddrBlock *netAddr); 


printerName is the NBP entity name for the printer 
(usually the contents of the PAPA -8192 resource). 

statusBuf points to a PAP status buffer (defined above). 
Upon return, it contains a human-readable string indicating the 
current status of the LaserWriter. 

netAddr is the address of an internet address block (defined 
above) , used to minimize NBP lookups during repetitive 
status calls on the same printer. You should initialize the 
contents of the address block to zero before making your first 
PAPStatus call. After the first call (if successful) the address 
block will contain the internet address of the printer you 
specified in the printerName parameter. Thereafter, the PAP 
Manager will try to use the address in the block rather than 
perform another NBP lookup. If for some reason the printer 
stops responding at the cached address, the PAP Manager will 
automatically revert to an NBP lookup and start the cycle 
again. 


PAPUnload: 


This function must be called prior to unlocking or 
releasing the memory occupied by the PAP Manager. The 
PAP Manager maintains several timers which are controlled 
by a VBL task. If the code for the VBL task vaporizes, the 
next time the VBL timer expires, the system will jump into 
garbage. 


pascal short PAPUnloed() 


Hooking Up to the PAP Manager 


The first thing we need to use the PAP Manager is a set of 
“glue” routines that provide a function-calling interface to the 
PAP Manager calls. We also need the code to locate, load and 
lock the PDEF-10 resource. This section describes a general- 
purpose interface module that provides these services. The 
mechanics of preparing the PAP Manager code resource 
(PDEF-10) for use are implemented in a PAPLoad() call which 
is added to the "real" PAP Manager calls just described. 


‘+ 


KKKKKKKKKEKEKKKE 
* PAPIntfc.asm * 
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X*Xx*xx*xxxxxxxxxxx 


calling environment. 


Written by: 
Bob Denny 
Alisa Systems, Inc. 
July, 1986 


FEE Ww Ww We He We We We We He We We We we We We 


Include Traps.D 
Include SysEqu.D 
‘Include  FSEqu.D 


Following has been wrong in equates forever 


ioNamePtr equ ioFileName 


is open. 


XXXYXXXXXXXXXXXXXEEEE 
**x WARNING *** 


X x x xx xoxoxoooeeeeopooeecx 


"e o We We We Be U We We We We & 


handle in dCtlVars. 


pepHnd' : 


dc.1 9 . ; Handle to PAP manager resource 


pepPtr: 


dc.1 8 ; Points to locked PAP manager 


entHndl : 


dc.1 Ø ; Handle to locked entity name 


Dynamic (stacked) data 


Open PAP connection 


we We We We We We 


xdef papOpen 


pepOpen: 
move. |] pepPtr,e 
jmp 9(ab) 


Receive data from PAP server 


xdef papRead 


papRead: 
move. | papPtr, ad 
jmp 4Ca0) 


f Send data to PAP server 


) 


xdef papWrite 


papWrite: 
move. | papPtr, ad 
jmp 8Ca0) 


* Get PAP server's status 


xdef papStatus 
pepStatus: 
move.] pepPtr,a 


Low level interface to the PAP manager for LightSpeed C 
and anyone else who uses Mac/Lisa standard Pascal 


NOTE: The name 'LaserWriter' is assumed here. The 
name of the resource file can be different. 
the STR resource in the System file that holds the name 
of the currently selected printer type, etc. 


Should look at 


NOTE: Uses new assembler equates & D files from 
Software Supplement, Vol. 1 No. 3, March '86 mailed July. 


Private local storage. Lives during the time the driver 


Static data here requires dNeedLock bit set in driver. 
You can change this by allocating space & storing the 
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jmp 12Ca0) -HGetVInfo ; HFS Get Volume Info 
j bne plErr ; (huh?) 
; Close PAP connection move .] ioVFndrInfoCa), ioWDDirID(Ca2) 
beq plErr ; Coops!) 
xdef papClose movea.]  82,a0 
papClose: -HSetVo1 ; Set default to blessed folder 
move. ] papPtr , ag bne plErr ; (huh?) 
jmp l6Ca) clr.w -(sp) ; Open the ‘LaserWriter’ fi 
h pea 'LaserWriter' 
; Load and lock the PAP manager -OpenResF ile 
; move .w (sp )+, LWfRef (a6) ,refNum of ‘LaserWriter' 
; Returns handle to entity name Cmp.w 8- |, LWfRefCa6) ; Error? 


; ; (yes, give up) 


beq plErr 
xdef papLoad j 
; Now the LaserWriter resource file is open 


) 


; Steck frame Clocal automatic) variables 


P e10: 
Subq.1 84 sp 
cur Vo] equ -2 move.] 8'PAPA',-Csp) ; Get the entity name 
; Client's default dir/vol saved here move .w "$E000, -Csp) 
LWfRef equ -2 + curVol -Ge tResource 
» fRefNum of 'LaserWriter' file lea entHnd1, a0 
ioParam equ -ioFQelSize + LWfRef move.1] (sp)+, (að) ; Entity handle 
,MFS/HFS file I/0 params beq.s plErr 
ioHVParam equ -ioHVQElSize + ioParem 
, HFS Volume Info params move. | entHndl, ag ; Lock entity string 
frameSize equ ioHVParam -HLock 
move.] entHndl, -Csp) 
papLoad: -DetachResource ; Hide it from Rsrc Mgr 
link 86, !frameS ize 
move &2,-Csp) ; Save A2 Subq.1 84 sp ; Get the PAP manager 
move. ] 8'PDEF',-(sp) 
lea pepHnd] , a£ ; Init for error handling move .w 810,-Csp) 
clr.1 (a£) -GetResource 
lea papPtr, a lea papHnd1, ad ; (dumb 68000 designers) 
clr.1 (a) move. ] (sp)+, (að) ; Handle to PAP manager 
lea entHndl, ad beq.s plErr ; Coops) 
clr.1 Ca) 
; nove.] pepHnd1 , ad 
; This mess gets the PDEF-10 resource from the -HLock ; Lock it down 
; LeserWriter file on the boot volume without making a move.| = papHnd1, að 
; permanent change in the current default volume. Note, lea papPtr,al ; (geez!) 
; HFS volumes require more work to find the file in the move.| (að), (al) ; Save ptr to PAP mgr 
; ‘blessed’ folder. move.] — papHndl,-(sp) 
; -De tachResource ; Hide it from Rsrc Mgr 
lea ioParam(a6),a2 ; a2 -> ioParam 
clr.1 ioCompletion(a2) move.w -4(86), -Csp) ; LeserWriter' refNum 
clr.] ioNamePtr(a2) -CloseResFile ; Close 'LeserWriter' 
movea.]  e2,a0 ; ^? ioParams 
_GetVol ; **MUST WORK** nove.] entHndl, -Csp) ; Return entity handle 
move.w — ioVRefNumCa2),curVo1(a6) ; Seve it bra.s plRet 
movea.] VCBQHdr+2,a8 ; Boot vol ist on VCB Q 
move.w  vcbVRefNum(ad), ioVRefNum(a2) plErr: — clr. -Csp) ; Return ni] 
;Boot volume VRefNum handle 
move. 1 82,80 
_SetVol ; Switch to boot volume plRet: move .W curVol(a6 ), ioVRefNum(a2) 
bne plErr ; (huh?) ; Get original default volume 
clr.w -(sp) ; Open the 'LaserWriter' file move.|  82,e0 
pea 'LaserWr iter ' tst.w FSFCBLen ; MFS or HFS? 
move.w (sp )+, LWFRef (a6) ; refNum -HSetVo1 ; Restore orig default vol/dir 
cmp.w 8-1 LWfRef (a6) ; Error? bra.s = @28 . 
bne e 10 ; Cnope) 610: _SetVol ; Restore original default vol 
; 620: move.] (sp?*,dÜ ; Restore return value 
; Failed to find LaserWriter. If on HFS, we can try to move.)  (sp)+,a2 ; Restore 82 . 
; find it in the System Folder ('blessed' folder). See unik o6 ; Standard Pascal function return 
; Macintosh Tech Note #67 "Finding the Blessed Folder". move.)  (sp)+,að ; «return Address) 
f ,,,89ddq *8,sp ; (no parameters) 
E T" FSFCBLen move.| — d, (sp) ; (Return Value) 
bmi plErr ; Coops, not running HFS system) jmp (að) ; Return 
lea ioHVPeram(a6),80  ; að -> HFS volinfo PB , 
cir.1 ioCompletionCad)  ; Set it up for the call| ; Unload the PAP manager. Should be called via 
clr.1 ioNamePtr(aQ) , needGoodBye' if used in driver or D/A. 
clr.w ToVRef NumCa) " 
clr.w ioVolIndexCa) xdef papUnload 


papUn load: 
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link a6, 8-2 


clr.w -2(a6) ; Justin Case 
move. | papPtr, a0 
beq.s e 10 
subq. 1 82,Sp 
jsr 20(8a0) ; Real PAPUnload 
move .W C(sp)+,-2€a6) ; Save PAP result 
8619: move. 1 entHndl, ad ; Junk entity 
beq.s e20 
HUn lock 
move. | entHnd1 , að 
_DisposHandle 
e20 : nove.1 papHndl,a ; junk PAP Manager 
beq.s 30 
-HUn lock 
move. 1 pepHnd1, e£ 
-DisposHandle 
@30 : move -2C(a6),d0 
unlk a6 ; Standard Pascal exit 
move. ] (sp )+, a8 ; return address 
;,,eddq %8,sp ; (no parameters) 
move.w d, (sp) ;function result 
jmp (að) return 
end 
A Driver for PAP 


Now that we have an interface for the PAP Manager, we 
can build a driver that will provide applications with a vanilla 
interface to the LaserWriter. 

The example driver does not support read or status 
operations. All incoming data from the LaserWriter is thrown 
away. This makes it very easy to write applications that just 
send to the LaserWriter and don't care what comes back. A 
commercial-quality application should handle reading from the 
LaserWriter and sending periodic status requests. The driver 
can be easily modified to support these things. 

The driver is written for LightSpeed C, which 
automatically sets some of the driver flags in the header. This 
driver must have dNeedLock, dNeedTime and dNeedGoodBye 
set. The control routine handles controlled and emergency 
(dNeedGoodBye) unloading of the PAP manager & entity 
string, as well as reading from the LaserWriter. Note that 
reading is attempted in the prime routine while the driver waits 
for the write to complete. I had to do this because SmallTalk- 
80 doesn't call SystemTask, so the driver never gets any 
dNeedTime control calls. LightSpeed C also handles the 
choice between returning to the system via RTS or JIODone, 
so be careful if you have to do this yourself. 

Finally, the glue routines are simplified because 
LightSpeed C has a “pascal” function call feature. If your 
compiler doesn't support this, the glue routines must change 
from your compiler's call frame to that expected by the Mac 
toolbox (ie, left to right push on the stack). 

Here is a sample program in MacPascal that uses the PAP 
driver and PAP Interface to print a little message on the 
LaserWriter. Note that this is a VERY inefficient use of PAP, 
as MacPascal does single character writes! Since we are 
writing directly to the LaserWriter, our text must be in 
PostScript because we are not going through LaserPrep as the 
Printing Manager does. [We'll save that topic for another day, 
hey Bob? -Ed] However, it is easy to format our text in a 
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Postscript context as the example shows. 
program PepDemo; 
ver 


laser : text; 

begin 
open( laser, '.PAP'); 
writeln( laser, 

' /showline ( gsave show grestore Ø -14 rmoveto ) def '); 
writelnClaser, '/Courier findfont 12 scalefont setfont'); 
writelnClaser, '50 750 moveto'); 
writelnCleser, '(Now learn PostScript, and) showline'); 
writelnClaser,'(keep reading Mac Tutor!) showline'); 
writelnClaser, 'showpage'); 
close( laser); 


David E. Smith 


Watch the LaserWriter! 


Implementation Details 
By 
David E. Smith 


The whole concept of drivers may seem confusing, and on 
the Mac it is! What our assembly language interface does is 
hunt for the LaserWriter file, hopefully in the "blessed folder", 
and opens it as a resource. Then we snoop into the LaserWriter 
file for two resources, "PAPA E000" and "PDEF 10", which 
we steal using GetResource, and lock in memory. We then 
provide access to the PDEF 10 resource, we learned is the 
PAP Manager, by setting up calls to the PAP Manager for 
open, read, write, status and close. Finally, we arrange to 
unload the PAP Manager when we are done with it. This is 
the purpose of the assembly interface. Compile the assembly 
code with either MDS assembler or Consulair C, or some 
other compatible assembler. The resulting ".REL" file will be 
linked to our driver. 

Once we have an interface to this bit of code in the 
LaserWriter file, we need a driver. The driver here was written 
in LightSpeed C, so it may not look exactly like a driver you 
are used to seeing in assembly. This is because LightSpeed C 
does a lot of housekeeping for you relative to drivers. The 
manual has an excellent discussion of why they do this, which 
is generally related to the problems of how drivers return, via 
RTS or JIODone. As the manual points out, most people do 
this wrong, so LightSpeed figures out how to do it right and 
sets up all the driver header information for you. This might 
seem a bit inflexible if you are used to doing everything your 
own way, but is very nice if you are unfamilar with 
Macintosh drivers and just want something that works. As a 
result, the driver source code has a MAIN with a case 
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statement, required by LightSpeed C. The BUILD DRIVER 
function uses this case statement to create the necessary driver 
header information for you. 

LightSpeed C also does some other things that you might 
not consider standard. When the driver is built, a DATA 
resource type is created in the driver file. Both the DRVR and 
this DATA resource must be moved from the driver file into 
the system file in order for the driver to work properly. This 
fact was unknown to me and I spent six hours trying to figure 
out why the driver wasn't working properly. The DATA 
resource has to do with the driver's global variables and is 
purely a creation of LightSpeed C's build driver function, You 
can also move the DRVR and DATA resources into your 
application file (which is also a resource!). I tried this and it 
workds too. In fact, it works better, because you don't have to 
re-boot the system after using ResEdit, as you do if you move 
the driver into the system file. Also, it is always present for 
those applications which you've written code to open it. 

Because LightSpeed C works under an invisible shell, 
there is no external link file. But the assembly interface and 
the C driver source code must be linked together and the driver 
created. This normal linking step is almost invisible in 
LightSpeed C so it's easy to forget that other compilers have 
to provide this step. The reason it's invisible is that both files, 
after being compiled, are loaded into what is called "a project" 
and are instantly available at all times. In addition, a seperate 
"VOC" file can be created that specifies case requirements for 
upper and lower case names. The manual goes into detail on 
various C compilers and how they deal with upper and lower 
case, as well as other compiler dependent problems. The 
manual is very well done, easily the best I've seen of any of 
the development systems. It looks like a normal (ie non- 
Macintosh) language manual, specifying the syntax of each 
command. For some reason, compiler developers on the Mac 
assume Mac programmers know their language by heart and 
rarely provide a language definition manual! 

Once the assembly source is assembled, the C source 
compiled, the two linked and a driver created, that driver is 
then installed in the system file or our application file, using 
ResEdit. Remember, if created with LightSpeed C, both the 
DATA and DRVR resources must be copied into the system 
file. Also, the purge bit and system heap bits should be set 
with the GETINFO ResEdit command, if using the MacPascal 
example. 

TML File I/O Example 

With the driver installed in the system file, any file I/O 
command can be given to open and write to the driver. Bob 
gave a simple MacPascal example. Here is the same example 
in TML pascal with a bare minimum event shell. A window 
is put up that says "look at the laserwriter" and then the text is 
printed out. A click of the mouse exits the program. Providing 
a simple shell program makes debugging easier. 


Program PapTest; 


( By D. Smith for MacTutor) 
( Uses standard Pascal file I/0) 
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($I MemTypes.ipas ) 
($1 QuickDrew.ipas ) 
($1 OSIntf . ipas ) 
($1 ToolIntf.ipas ) 
($I PackIntf.ipas ) 


($T APPL 7777 ) 
VAR (global program stuff} 


laser: text; (pascal file ref} 


PROCEDURE InitIt; 
begin 

InitGraf(@thePort); 

InitFonts; 

Ini tWindows; 

InitMenus; 

TEInit; 

InitDialogsCNi1); 

InitCursor; 
FlushEventsCeveryEvent, 0); 
ne ) 
PROCEDURE writeItCtxt:str255); 
begin 

writelnClaser, txt); 

end; 


DrvrNeme: str255; 
begin 

DrvrName:z'.PAP'; 

openClaser,DrvrName); 


( put your text in PostScript Format!) 
A writeIt('/showline ( gsave show grestore Ø -7 rmoveto ) 
def '); 
writeItC'/Courier findfont 7 scalefont setfont'); 
writelt('58 750 moveto'); 
writeItC'Cthis is a line) showline'); 
writeItC'Cso is this!) showl ine '); 
writeItC'showpage'); 


Close( laser); 
end; 


( 
PROCEDURE SetupWindows; 
Var WRect: Rect; 
wtitle:  str255; 
wtype: integer; 
Vis: boolean; 
GoAway: boolean; 
RefVal:  LongInt; 
wptr: windowptr; 
Begin 
SetRect(WRect, 10, 40, 230, 150); 
wtype := 16; 
wtitle:='David E. Smith’; 
Vis := true; 
GoAway := false; 
Ref Val :=0; 
wptr := NewWindow(Nil,WRect,wtitle,Vis,wtype, Nil, 
GoAway, Ref Val); 
SetPort(wptr); 
TextFont(Geneva); 
MoveToC 1,30); 
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DrawStringC'Watch the LaserWriter!'); 
MoveTo( 12, 30); 
Move(@, 15); 


PROCEDURE MainEventLoop; 
Var Event:EventRecord; 
myevent: Boolean, 
Begin 
Repeat 
SystenTesk; 
myevent := GetNextEventCEveryEvent, Event); 
If myevent then 
Case Event.what of 
mouseDown : closeup; 
End; (of Case) 
Until False; 
End; 


InitIt; 
SetupWindows; 
LaserIt; 
MainEventLoop 


END. 
Device Manger Format 


Our code above simply mimics the MacPascal example by 
opening a text file, which we assign to our PAP driver, and 
then writing lines of text to it, which are really postscript 
commands. Note that when we open the file someone goes out 
and looks first in the system file or the application file to see 
if we have a driver by that name (who?). Since we do, the 
driver is opened instead of a file on the disk. One thing I 
discovered after another six hours of frustration is the 
LaserWriter wants an end of line character before it will do 
anything. Using the writeln statement as we did above 
provides that. But when we use the Device Manager, we have 
to send an eol to get anything to print out. In the second 
example below, we modify the WriteIt and LaserIt procedures 
to use the Hight Level Device Manger calls instead of the 
vanilla Pascal file statements as we did in the previous 
example: 


Program PepTest2; 


( By D. Smith for MacTutor) 
( Uses High level Device Manager) 


VAR (global program stuff) 


laser: integer; (file ref) 


PROCEDURE writeltCtxt:str255); 


CONST 

eol=13; 
var 

StrLen: LongInt; 

err: oserr; 

CR: str255; (two bytes?) 
begin 


CR:2chrCeo12; 
StrLen:=length(txt); 
err :=FSWriteC laser, StrLen, POINTERCORDC@txt )+1)); 
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StrLen:=length(CR); 
err :=FSWrite( laser, StrLen, POINTERCORDC@CRD+1)); 


OrvrName: str255; 
err :oserr; 
begin 
OrvrName :=' .PAP' ; 
err :=OpenDr iver (DrvrName, laser); 


( put your text in PostScript Format!) 
m NT lecc/snonline ( gsave show grestore Ø -7 rmoveto ) 
ef'2; 

writeItC'/Courier findfont 7 scalefont setfont' 2; 

writeIt('59 758 moveto'); 

writeItC'Cthis is a line) showline'); 

writeItC'Cso is this!) showline'); 

writeItC'showpage ' 2; 


err :=CloseDr iver( laser); 
end; 


In the above example, we use the high level device 
manager calls to open a driver by name, and then write to it 
with FSWrite. However, we must also write out a carriage 
return to get the LaserWriter to output anything, so our 
WriteIt procedure has been modified to do this. The rest of the 
code is the same as before. 


Low Level Device Manager Calls 


In our final example, we again modify the above code to 
use the low level device manager PB Write command. For this, 
we need an ioParam block. We stuff the parameter block with 
the length of each line and a pointer to the text and issue the 
PBWrite call using a pointer to the parameter block. (There is 
probably a cleaner way to handle the carriage return, but as I 


said last month, I don't understand typecasting! Anyway, this 
worked!) 


Program PapTest3; 


( By D. Smith for MacTutor) 
( Uses low level Device Manager) 


VAR (global program stuff) 


pb: PermBlkPtr; (ioParem Block) 


( ————— —————— ——— 
PROCEDURE writeItCtxt:str255); 
CONST 

e0l=13; 
var 

StrLen: LongInt; 

err: oserr,; 

CR: str255; (two bytes?) 
begin 


CR:2chrCeo1); 

StrLen:=length( txt); 

pb*. ioReqCount:=StrLen; 

pb*. ioBuf fer :=POINTERCORDC@txt)+1); 
err :=PBWrite(pb, false); 
StrLen:=length(CR); 
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pb^. ioReqCount :=StrLen; 
pb^ . ioBuf fer :=POINTERCORDC@CR)+1); 
err :=PBWriteCpb, false): 


DrvrName: str255; 
err:oserr; 
begin 
DrvrName:=' .PAP'; 
pb^. ioNameP tr :=@DrvrName; 
pb”. ioPermssn:=2; write only) 
pb^.ioCompletion:znil; 
err :=PBOpen(pb, false); 


( put your text in PostScript Format!) 

writeItC'/showline ( gsave show grestore Ø -7 rmoveto ) 
def '); 

writeItC'/Courier findfont 7 scalefont setfont'); 

writeIt('58 758 moveto'); 

writeItC('Cthis is a line) show] ine' ); 

writeItC'Cso is this!) showline'); 

writeItC'showpage ' 5; 


err:-PBClose(pb,false); 


end; 
End of Sample Programs 
3 PAP Driver 


* This driver allows applications, etc. to communicate 
* with the currently selected LaserWriter via Standard 
* Mac I/0 calls. 

*/ 


/* macintosh headers */ 
"include <DeviceMgr .h> 
"include «FileMgr.h» 


/* n-bit signed integers */ 
"define int16 int 
"define int32 long 


ee struct /* pap status record */ 


int32 systenStuff ; 
char statusStr[256]; 
) papStatusRec, *papStatusPtr; 


int 16 prefnum; /* pap refNum */ 

Handle entity; /* h to server entity name 
*/ 

papStatusRec status; /* pap status */ 

char rbuff [512]; /* read buffer */ 

int16 rsize; /* read size */ 

int16 rstate; /* Status of PAPRead */ 
int16 reof ; /* Set to read EOF status 
*/ 

/* 


* Assembly Interface to PAP Manager 
"I 


extern pascal int16 papOpenO; 

extern pascal int16 papRead():; 

extern pascal int16 papWrite(); 
extern pascal int16 papStatus(); 
extern pascal int16 papClose(); 
extern pascal Handle papLoadO; 
extern pascal int16 papUnload(); 


/* 


* Driver Dispatch routine (non-standard, for LS C!) 
£/ 
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OSErr main(pb, dce, op) 
DCtlEntry *dce; 

ioParam *pb; 

int a 


HD 


case Q: /* Open */ 
return(drvropen(dce, pb)); 

case 1: /* Prime */ 
returnCdrvrprimeCdce, pb)); 

case 2: /* Control */ 
return(drvrctlCdce, pb)); 

case 3: /* Status */ 
return(drvrstatus(dce, pb)); 

case 4: /* Close */ 
return(drvrclose(dce, pb)); 

default: 


) 


4 


/* 
x 
af 
int16 drvropen(dce, pb) 


DCtlEntry *dce; 
"aai Xpb; 


int16 ostate; 
int16 pres; 
int16 drvrclose(); 


dce-'dCtlFlags |= dNeedGoodBye | dNeedTime; 
dce-?dCtlFlags &- "dReadEnable; /* No Read for now */ 
oe &= "dStatEnable; /* No Status for now 


dce-?dCtlDelay = 12; 


/* 5 Hz. cycle rate */ 
rstate = 1; 


/* Disable 5 Hz reads for now x / 


pres = noErr; 

entity = Ø; 

prefnum = -1; 
eae = papLoad()) 


/* PAP not loaded */ 
/* No connection */ 


status.statusStr[0] = ‘\g'; 
String */ 

if(Cpres = papOpen(&prefnum, *entity, 1, &status, 
&ostate)) == noErr) 


/* Clear status 


whileCostate > Ø) 


ea = ostate; 


) 
else 
pres - openErr; 


if(pres != noErr) 


prefnum = -1; 
drvrcloseCdce, pb); 


/* PAP connection not open */ 


else 
papRead(prefnum, rbuff, &rsize, &reof, &rstate); 


return(pres); 
/* 
* Close 
*/ 


int16 drvrcloseCdce, pb) 
DCtlEntry *dce; 
ioParam *pb; 
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int16 pres; 
int16 wstate; 


pres = noErr; 
if (prefnum >= 9) 


/* Exchange EOF messages, then close */ 


ifCCpres = papWriteCprefnum, "", Ø, 1, &wstate)) == 


noErr ) 
whileCwstate > 8) 
while(rstate > 0) 


4 


di = papClose(prefnum); 


ifCentity != 6) 
pres = pepUnload(); 


return(pres); 


/* 


* Control 
x 


* Called at 2Hz and for needGoodBye, also called during 

* wait loop in the ‘write’ routine, since some apps don't 
* call SystemTask (namely Snalltalk-80! ). 

i 


int16 drvrctlCdce, pb) 
DCtlEntry *dce; 
cntr1Param *pb; 


/* If goodBye, shut down */ 
if(pb-»csCode == -1) 
return(drvrclose(dce, pb)); 


/* If KillIO, just return */ 


if(pb-»csCode == 1) 
return(@); 
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/* if last papRead finished, try another. */ 
if (rstate <= 9) 


papRead(prefnum, rbuff, &rsize, &reof, &rstate); 


returnC0); 


/* 
* Prine 
* A11 read/write calls from the device manger 
* come here to the Prime routine. 
*/ 
int16 drvrprimeCdce, pb) 
DCtlEntry *dce; 
uias *pb; 


int16 pres; 
int16 wstate; 


ifCCpb-» ioTrap & OxFF) == aRdCmd) 
return(readErr ); /* Should not happen Cha) */ 


ifCCpres = papWriteCprefnum, pb-> ioBuffer, Cint 16)pb- 
»ioReqCount, 8, &wstate)) == noErr) 


whileCwstate ? Ø) 
if (rstate <= 8) 
papRead(prefnum, rbuff, &rsize, &reof, &rstate); 
res = wstate; 
eas ha 
/* 
oe Cinop) 
int16 drvrstatus(dce, pb) 
DCtlEntry *dce; 
coe *pb; 


aii g; /* Not implemented! */ 


CEP. 
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EM 


C Workshop 


Batch Document Selector in Mac C 


Everybody Needs a Front Man... 


One of the more annoying "features" of the Finder is its 
habit of keeping all selections within a single folder; files 
selected in folder 'A' suddenly unselect when you click outside 
it. This is restrictive if you have a hard disk: typically there's 
one copy of an application, with files scattered all over the 
back 40. If you wanted to print a batch of them, from different 
folders, you were out of luck and had to babysit the Mac all 
the way thru. What we need is a utility that selects multiple 
files from a user dialog, then processes or sends the whole lot 
off to some other program or function. In otherwords, a front 
man to do a batch job for us! The Front Man is just such a 
general-purpose document-batching utility. 

The Front Man was written to overcome this Finder 
limitation by providing a general purpose multi-file selector, 
and to show the use of the Launch trap from 'C'. While 
obscurely documented in Inside Mac, there is a lot of potential 
in this trap! A number of other principals are also shown here, 
Such as user configurability, HFS compatibility, and the use 
of the finder parameters. Following the guidelines here will 
teach you how to write HFS programs that work, and explain 
why some things are still tough to do with an HFS type file 
Structure. 

Front Man: List Selection of Files 

Choose "Pick" to bring up a standard getfile dialog box. 
Each time you select a file, it is added to the list to be passed 
via the finder parameters to another application. Hit the cancel 
button to quit selecting. An exception is if a file name ends 
with '.FILE' - in this case, the file is assumed to contain a list 
of file names (1 per line) which are each added to the finder 
parms. It can (optionally) display ALL file types, not just 
TEXT files (so you can batch files to WORD, MacWrite, 
etc.). The only shortcoming is that when using a file of 
filenames, it doesn't look up the directory entry for each file 
named, and get the proper filetype; instead, the filetype of the 
batch file is applied to each named file (this limits the utility 
of batch files to TEXT files, but offers "an exercise for the 
student"). 

Choose "Launch". If you are in "interactive" mode, a 
standard getfile dialog box will appear displaying applications. 
If you are in "hardwired" mode, the application whose name is 
in a STR resource is launched automatically, with the list of 
files sent on in your behalf! 

Front Man can (optionally) cause the launched application 
to either print or just open the selected files. 

Uses ofthe Launch and Chain traps 

One of the most common arrangements in traditional data 

processing systems was chained programs, Program 'A' ran to 


O The Complete MacTutor, Vol. 2 


Frank Alviani 
Contributing Editor 


The Front Man 


The Front Man... 


You can select any number of files using 


the standard file dialog. RII of these files 
will be passed at once to the application 
to be printed when you select "Launch" 
from the file Menu. 


GOTCHR! 


Sort or preprocess a bunch of data, then chained to program 'B' 
which did the reports or other interesting work on the data. 
This was done to be able to work with large data sets on 
smallish machines (by today's standards), and also allowed 
very long processing runs to be broken up into smaller pieces. 
Programmers also found it more convenient in many respects - 

the smaller programs were easier to debug and write: all the 
classical virtues of modularity. 

The difference between chaining and launching is small: 
when you chain to a program on a Mac, the application heap 
is preserved essentially intact. When you launch another 
program, the heap is reset except for the desk scrap. 
ExitToShell, for example, simply launches the program 
whose name is found in low memory at $2EO. Chaining is 
thus useful when the different programs want to pass blocks of 
data in memory, as might be the case in an "integrated" 
processing package; launching is more useful in more general- 
purpose "front ends" such as this. 

"Front Ends" have a small but useful niche to fill. For 
example, a "program tuner" might batch a number of 'C' files 
together, have them all compiled to assembler, optimize at 
this level, then assemble the tuned files. Also, a set of options 
(ala conventional 'C' command-line parameters) could be 
gathered and placed in a block in System memory before 
launching another application which would know where to 
look... 

Basics of the Finder Parameters 

The finder parameters are what make "front ending" an 
application possible. They consist of 3 pieces of information: 
(1) A "message" to the application about what to do with the 

files. The operation requested is applied to ALL the files 

named. 
(2) A count of how many files to process. 
(3) A list of the files to process, with complete location 
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information (volume reference number as well as file 
name). 


(meten ore 


File Name characters 


CRITICAL!! 


Must Be Zero! 


Document 1 


Pascal-style string 


More documents.. 


Currently, the only messages in use are "print" and 
"open". Since "message" is a 16-bit field, this leaves 65.766 
operations available! There is no reason why "private" 
message types can't be developed, such as "sort each of these 
in ascending order", "sort each in descending order", "merge 
these all together ", etc. as long as the application getting the 
message is equipped to deal with the additional messages! In 
an even more flexible system, the first file in the list could 
contain parameters that dictate what processing is done to each 
of the following files in the list - that is, another type of 
command line type facility!! (Hmm, that's not a bad idea - 
maybe I'll write a general command line front end next....) 

I used a set of routines written by Andy Shebanow to 
access the finder parameters. A couple of minor corrections are 
noted. 

One minor fact to note if you intend to start building your 
own finder parameters: the finder-info relocatable block is 
locked on entry to your program and must be unlocked before 
you can start manipulating it! 

Configurabllity 

It is usually desirable to allow a program to be configured 
by its user. If the usage will change frequently, menu choices 
are probably the best route; if usage will be stable once settled 
on, it's less obtrusive to configure the program by using 
ResEd to set values in STR or STR# resources. Here, we've 
gone the ResEd route, using STR resources to determine the 
programs behavior in a simple fashion. 

STR #259 determines if only ‘TEXT files are to be displayed 
(if it contains the string TEXT) or if all types are to be 
shown (if not ). 

STR #258 determines if the launched application should print 
the files (if it contains the string PRINT) or just open them 
(if not). 

STR 4257 determines. if the program is in "interactive" mode 
(if it contains the string ASK) or in "hardwired" mode (if 
not). 

STR #256 contains the name of the application to launch in 
"hardwired" mode; , 

Yer gonna love the Munger 

This is one of the most useful - and overlooked - little 

routines in the entire Toolbox! The documentation is hidden in 
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the Toolbox Utilities chapter at the end of volume I of Inside 
Macintosh. It allows searching for substrings, string insertion, 
string replacement, and string deletion: all with a single chunk 
of code! The table if fig. 3 summarizes how the munger is 
used; see IM for the details... 

Here, we use it to check STR resources for specific 
substrings to decide how the program is going to behave. Just 
checking to see if a STR contains a given substring is more 


tolerant than requiring an exact match. The STR is "folded" to 
uppercase (lowercase would work equally well) before the 
match so the test is case insensitive. The only minor point to 
remember in 'C' is that any non-negative result is a success - a 
common shortcut is to simple check for non-zero for success. 

The tiny routine CheckStr reads in a STR resource, folds it 
to uppercase, and tries to locate a given substring; the output 
from the Munger is returned as the result. 

HFS Compatibility 

This really isn't terribly difficult if you follow the rules. 
The failure of most development system publishers to be HFS 
compatible is totally unreasonable! 

As has been documented countless times by now, the new 
file system is a fairly conventional tree-structured directory 
system. Each directory can be considered to be very much like 
an entire volume, with a link to the directory above it in the 
tree. Since each directory is almost independent, you must 
have the problem of potentially identical file names, and 
therefore you must specify a volume or directory as part of the 
file name. To avoid this would require unique names for all 
files in the system, which is ludicrous (try keeping unique 
names on ALL YOUR FLOPPIES, which is logically 
equivalent!). 

This has been known for decades, since the first disks came 
into use. The concept of a "working directory" is part and 
parcel of Unix: either you are referencing your working 
directory, or you have to give a complete path to find a file, 
starting at the device level. 

As a shortcut, "search paths" were developed, such as the 
new Consulair path manager - for a given type of file, the 
system is given a set of partial path names, which are prefixed 
to the plain file name to come up with a complete path name 
(which is still needed). Each partial path name is prefixed to 
the plain file name in turn until the system either finds the file 
or quits in disgust. 

The basics are simple: either give a complete path name or 
make sure the system knows which volume/directory you are 
referring to. For appl- ications, this means using SetVol to 
set the default volume; with files, the volume reference 
number field must be filled in correctly. 

In The Front Man, both the application to launch and the 
files to process can be located anywhere. The SetVol 
parameters for the application are taken from the SFGetFile 
record in interactive mode, or a full pathname must be 
provided in the STR resource (a full pathname for anything 
has highest priority in searching). A similar approach is used 
in setting the volume reference number for the finder 
parameters. 

Unfortunately for 


developers, there is no 
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Fig. 3 The Munger Trap 


fundamental mechanism built into the HFS type 
of system that allows you to automatically know 


where certain files "ought" to be located. In the 
Unix-type world, there is usually none either, except that 
applications conventionally all reside in a directory called 
"cmds" or something similar (a solution which is unusually 
awkward with the Mac interface for obvious reasons). 
Applications can make use of a path manager-type system if 
they wish, but that's still not part of the system. The closest 
we could come would be to build a path-manager facility into 
the ROMs and have individual applications provide "search 
path" resources customized to their needs. Total consistency 
would not be achieved, since different search paths would and 
could be created, but it might be a small step forward. And 
remember, with search paths, if you frequently restructure your 
folders, you'd have to restructure all your search paths at the 
same time! 

Now that we've explained once again how easy HFS 
compatibility is for the average application, the development 
system vendors look even worse! Minor glitches aren't terribly 
surprising, but for the authors of Xenix (one of the best- 
selling Unix clones on the market), for example, to have an 
HFS-incompatible Fortran system on the market 6 months 
after the Mac* was released and far longer after they knew 
what was required (since they probably had a hand in setting 
the specs) can only be explained by a corporate disregard for 
the Macintosh world (Microsoft didn't write Fortran 
themselves). Their conventional applications don't have quite 
as many problems, but still can't be called 10096 compatible. 
Bah! Humbug! 


/* The Front Men, Ver. 1.0 
* Frank Alviani 
* This version does NOT support desk accessories 
x/ 

Options +Z 

* include "stdio.h" 

8include "macdefs.h" 
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sjeje| [M|v] [r[sTw Destination string 


Target string (ptr1/len1) 


Replacement string (ptr2/len2) 


Outcome 


In destination string, a substring of Lent is 
replaced by replacement string. If 
offset to end of destination strin 


REPLACEMENT string simply inserted — into 
destination string at offset. 


Destination searched for TARGET st ring. 
Returns offset if found, -1 if not 


TARGET string deleted, since repla cement 
string is empty. 


®include "macCdefs.h" 
include "dialog.h" 
*include "events.h" 
®include "menu.h" 
8include "memory.h" 
8*include "OsIO.h" 
"include "packages.h" 
/* constants */ 
8def ine NULL Ø 
define EVENTMASK -1 
"define PBSetVol(pb, a) 
pbCallC(pb, a, 8xA015) 
/* menu constants */ 
"def ine APPLE 1 
“define ABOUT 1 
"define FILE 2 
Sdefine PICK 1 
"define LAUNCH 2 
8define QUIT 3 
*def ine APPPARMHANDLE 
/* finder application 
parameter info */ 
typedef struct ( 
short 
vRef Num; 


leni « O, 
g replaced. 


0xÜaec 


unsigned long  fType; 
Short versNum; 
Str255 fName; 

) AppFile; 


typedef struct ( 
Ptr pgnPtr; 
long dummy; 
) leunchStuff ; 
extern short AddAppFile(), MacCVRefNum; 
extern void SetAppMessage(), ZeroAppF ilesC); 
/* Globals */ 
MenuHandle 
EventRecord 
leunchStuf f 
oo 


short 


/* normal setting = Ø */ 


AppleMH, FileMH; 
theEvent; 
leunchParms; 


mouse.part, alert item; 
long nenu. selection; 
WindowPtr — tWindow; /* dummy to use FindWindow */ 
InitA11C); /* initialize various managers */ 
while C1) /* Usual Main Loop */ 
( if (GetNextEventCEVENTMASK, &theEvent)) 
SwitchCtheEvent . what) 
( cese mouseDown: 


mouse-part = FindWindow(&theEvent where, 
&tWindow); 


Switch C mouse.pert ) 
( case inMenuBer: 
menu_selection = 
MenuSe lect(&theEvent where); 
DoCommand(menu_se lection); 
break; 
default: break; 


break; 
cese keyDown: /* only for keyboard shortcuts */ 
if CtheEvent modifiers & cmdKey) 
( menu_selection = MenuKey(theEvent message & 


OxFF); 
DoCommand(menu_se lection); 
break; 
case autokey: /* no valid use for AutoKey 
events */ 
case updateEvt: /* no windows, so.... */ 
case activateEvt: 
break; 
) 
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) 
Co 


Ini tMenus(); 

TEInit(C); 

InitDialogsCNULL ); /* no recovery */ 
FlushEventsCOx00Q0FFFF); /* kill ‘em al1*/ 
InitCursor(); 

ZeroAppF iles(); 

AppleMH = NewMenuCAPPLE, "\p\824"); 

FileMH = GetMenuCFILE); 
AppendMenuCAppleMH, “\pAbout The Front Man;(-;"); 
InsertMenuCAppleMH, 9); 

InsertMenuCFileMH, 2); 

DrawMenuBar(); /* make it visible */ 


) 

AboutBoxC) 

( 

DialogRecord about; 
DialogPtr about. ptr; 
short item. hit; 


about_ptr = GetNewDialog(256, &ebout, -1); 
ModalDialogCNULL, &itemhit); 
CloseDialogCabout. ptr); 


/* Standard Menu tree — */ 
DoCommand(menu_cho ice) 
co menu_choice; 


short menu, item; 
menu = HiWord(menu. choice); 
item = LoWord(menu_choice); 
switch (menu) 
( case APPLE: 
AboutBoxC2; 
break; 
case FILE: 
switch Citem) 
( case PICK: 
getFiles(); break; 
case LAUNCH: 
LaunchIt(); break; 
case QUIT: 
ExitToShe11C); 


break; 
HiliteMenuC(0); /* turn off highlighting */ 


/* Use SFGetFile to get file names. STR #259 determines if */ 
/* only TEXT or all file types will be displayed, so */ 
/* Word,MacWrite, etc. files can be batched. */ 
/* Use the Munger to check the file name. If it ends */ 
/* in '.FILE', it holds a LIST of file names. Read each */ 
/* in turn and add to the finder parameters. */ 
/* Hit the cancel button in the SF dialog to quit.  */ 
a getFilesC) 


Point where; 

SFTypeL ist tType; 

SFReply aRep ly; 

AppFile fPerm; 

Handle fNemeH; 

short fNameLen, off, fino, numTypes, 
CheckStr(); 

Ptr wanted, wantedT; 


char f i le_name [641]; 
where.h = 75; where.v = 100; 
wanted = ".FILE"; wantedT = 'TEXT'; 
/* determine file types to display */ 
if CCheckStr(259, wantedT) >= Ø) 
( numTypes = 1; /* just TEXT files */ 
tType.ftype(@) = ‘TEXT’; 


else 
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( numTypes = -1; /* any kind of file */ 
tType.ftype[0] = NULL; 


/* get file names repeatedly */ 
while (1) 
( SFGetFileC&where, NULL, NULL, numTypes, &tType, NULL, 
&eReplu); 
if ClaReply.good) break; 
batching */ 
/* see if name end in '.FILES' - if so, it's a "batch" 


/* hit cancel to stop 


file */ 
fNameLen = aReply.Namelength; 
fNameH = NewHandle(CfNameLen* 1); 
BlockMove(&aReply.Namelength, *fNameH, fNameLen* 1); 
PToCStr(*fNameH ); 
setuppercase(*fNameH); 
off = Munger(fNameH, 8, wanted, 5, Ø, Ø); 
type */ 


/* check 


/* process selected file name */ 
if Coff?0) /* batch file */ 
( HLock(fNameH); 
MacCVRefNum = aReply.vRefNum; 
f_no = TKOpen(diskdevice, *fNameH, 1); /* read */ 
while Cleof(f.no2) /* read a name, add to batch */ 
( readlineCf.no, file_name, 64); 
CtoPStrCf ile_name); /* set up for Mac */ 
fParm.vRefNum = MacCVRef Num; 
fPerm.fType = eReply.f type; 
fParm.versNum = 9; 
fParm.fName.count = file_name([@]; 
BlockMove(&file_name(1], &fParm.fName.s[0], 


file_name(@1); 
AddAppF i le(&f Parm); /* edd to list */ 
TKCloseCf_no); /* clean up */ 
HUnlockCfNameH?; 


else /* normal name */ 
( fParm.vRefNum = aReply.vRefNum; 
fParm.fType = aReply.f type; 
fParm.versNum = £; 
fParm.fNeme.count = aReply.Namelength; /* copy */ 
BlockMoveC&aReply.Neme[2], &fParm.fName.s[0], 
aReply.Namelength); 
AddAppF i leC&fParm); /* add to list */ 


DisposHandleCfNameH); 


/* Decide whether the application should print or just open */ 
/* the picked files. Decide whether to use the "hardwired" */ 
/* application name or use SFGetFile to select the */ 

/* name and set the default volume. Launch application!! */ 


ru LeunchItC) 

Point where; 

SFTypeL ist tType; 

SFReply eReply; 

$tr255 target; 

Handle nameH, conf igH, msgH; 
Ptr wantedA, wantedMsg; 
short off, CheckStr(C); 


VolumeParam volPB; 
where.h = 75; where.v = 100; 
tType.ftype(8] = ‘APPL’; 
wantedA = "ASK"; wantedMsg = "PRINT"; 
/* determine whether to print or open batched files */ 
if CCheckStr(258, wantedMsg) >= Ø) 


Se tAppMessage( 1); /* ‘print’ */ 
else 
SetAppMessageC2); /* 'open' */ 


/* determine epplication to leunch */ 
if (CheckStr(257, wantedA) >= Ø)  /* use SFGetFile */ 
( SFGetFileC&where, NULL, NULL, 1, &tType, NULL, 
&eReply); 
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if CleReply.good) return; /* hit cancel to avoid 
launch */ 

/* SET VOL HERE!! */ 

volPB.ioCompletion = NULL; 

volPB.ioNamePtr = NULL; 

voIPB. ioVRefNum = aReply.vRefNum; 

PBSetVolC&volPB, Ø); 

target.count = aReply.Namelength; 

BlockMoveC&aReply.Name[2), &target.s(0], 
d d 


else /* use "hardwired" application name */ 

( nameH = (Handle) GetResource('STR ', 256); 
DetachResource(nameH); /* keep resource mgr happy */ 
target.count = **nameH; 

BlockMove(*nameH+1, &target.s(0], target .count); 


/* set up params and launch application */ 
leunchPerms.pgmPtr = &target.count; 

launchParms.dummy = Ø; /* normal configuration */ 
LaunchPgm(& launchParms .pgmP tr); 


/* --~ Check a STR resource for a given string (CASE 
INSENSITIVE) --- */ 

/* returns negative * if NOT found, non-neg if FOUND */ 
short CheckStr(StrNum, wanted) 

short — StrNum; /* STR * to check */ 

n wanted; /* ptr to string to check for */ 


Handle resh; 

short  strLen; 
resH = (Handle) GetResource('STR ', StrNum); 
strlen = length(wanted); 
PToCStrC*resH); /* RMaker builds Pstrings - need C */ 
Setuppercase(*resH); /* folds all chars to upper case */ 
return Munger(resH, Ø, wanted, strLen, Ø, 0); 


/* --- Launch Glue --- */ 
void LaunchPgaCperas) 
ud *parms; /* fake out compiler */ 


*tasm 

MOVE.L DØ AG 

DC.W  $A9F2 ; -Launch 
oe 


/* --- SFGetFile glue --- */ 
SFGetFileCwhere, prompt, fileFilter, numTypes, typeList, 
digHook, reply) 


Point *where; // DO) 
Struct PStr *prompt; //(D1) 

int (*fileFilter2C); //(02) 
short numTypes; //(€D03) 
SFTypeList *typeList; //(D4) 

int (*dlgHook2C); //(05) 
pen *reply; //XD6) 
asm 


Include MacTraps.D 
MOVE.L . D0,A0 
MOVE.L CAB), -CSP) ; WHERE 


MOVE.L — D1,-CSP) ; PROMPT 
MOVE.L D2, -CSP) ; FILTER PROC 
MOVE.W D3, -CSP) ; NumTypes 
MOVE.L D4, -CSP) ; WpeList 
MOVE.L — D5,-CSP) ; digHook 
MOVE.L D6,-CSP) ; reply 

MOVE #2,-C(SP) ; routine selector 
-Pack3 ;DC.W $A9EA ; -Pack3 


RTS 


Sendasm 
a 
/* 

* FinderParas.c Andrew G. Shebanow 8/31/85 

x 


* Routines to emulate the Pascal calls which return 
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* finder information (e.g., file arguments, open or print, 


etc). 


* Written to MacC. Copyright 1985 HyperSoft 
* This edition granted to MacTutor for publication. 


77 
®include "memory.h" 


/* finder message open files or print files */ 


"define appOpen ð 
#def ine appPrint 1 


/* finder application parameter info */ 


typedef struct ( 


shor t vRef Num; 
unsigned long f Type; 
short versNum; 
Str255 fName; 

) AppFile; 


"define APPPARMHANDLE — QxÜaec 
"def ine FinderName Üx2E0 
typedef struct ( 

short message; 

short count; 


AppFile files(4]; /* actually open ended */ 


) AppParms; 

Short AddAppFileCappFile) 
AppFile *appFile; 
( 


Handle appParmH; 
AppParms *appParmPtr; 
AppFile *newAppFile; 


unsigned long appHsize, appFsize; 


unsigned long newSize; 


appParmH 


(Handle) APPPARMHANDLE ; 


appParmH = (Handle) *appParmH; 


appHsize 


GetHandleSizeCappParmH); 


appFsize = Cunsigned long) appFile-?fName.count; 


appFsize**; 


if CCappFsize & 0x01) != Ø) 


appFsize**; 
appFsize *- 8; 


newSize = appFsize + appHsize; 
if (SetHandleSizeCappParmH,newSize) != Ø) 


return(1); 
appParmPtr = CAppParms *) 


>count]); * 


*appParmH; 


/* newAppFile = &CappParmPtr-»f iles[appParmPtr- 
/ 


newAppFile = CAppFile *) CCchar *) appParmPtr + 


appHsize); 


BlockMoveCappF ile,newAppF i le, appFsize); 


eppParmPtr-»count += 1; 
returnC2); 


o esmprocs() 


8asm 
INCLUDE MACTRAPS.D 
INCLUDE SYSEQU. txt 
INCLUDE TOOLEQU. txt 

; Routines declared here: 
XDEF CountAppF iles 
XDEF GetAppF iles 
XDEF ClrAppFiles 
XDEF ZeroAppFiles 
XDEF SetAppMessage 
XDEF GetAppName 
XDEF GetFndrName 
XDEF SetFndrName 


; Void CountAppFilesCmessage, count) 
9) 


; Short *message; 
; Short *count; (01) 
CountAppF i les: 
MOVEM.L A90-A2,-CSP) 
MOVE.L APPPARMHANDLE, AØ 
MOVE.L (CAO), AO 
MOVE.L D0,A1 


; save regs 


; M points to AppParms 
; Al points to message 
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MOVE.L D1,A2 
MOVE CAB), CAD 
; save into message 
MOVE 2(AB), CA2) 
MOVEM.L CSP )+,AQ-A2 
RTS 
; void GetAppF ilesC index, appF ile) 
; short index; (DØ) 
; AppFile *appFile; (D1) 
GetAppFiles: 
MOVEM.L A®-A2/D9-D1,-CSP) 
MOVE.L APPPARMHANDLE, Ad 
MOVE.L (AØ), AG 
AppParms 
MOVE.L 
JSR F indIndex 
CMP.L  *80,A1 
BEQ e1 
handle error 


D1,A2 


; copy AppFile data from A1 to app 
MOVE .L 


A1,A0 
MOVE.L A2,A1 
MOVE.L 8CA0), DØ 
AND.L  8$ØFF,DØ 
ADDQ.L #1,D9 
BTST #9 DO 
BEQ e? 
bytes... 
ADDQ.L #1,DØ 
byte 
82 ADD.L — *8,D0 
deta 
-BlockMove 
81 Bs (SP2*,A0-A2/00-D1 
RT 


; void ClrAppFilesCindex) 


; Short index; (DØ) 
ClrAppF iles: 
MOVEM.L A0-A1,-CSP) 
MOVE.L APPPARMHANDLE, A 
MOVE.L (A02,4A0 
AppParms 
JSR F indIndex 
CMP.L  *0,A1 
BEQ e1 
MOVE.L 80,2CADD 
field 
81 MOVEM.L CSP)+,AQ-A! 
RTS 


; void ZeroAppFiles(C) 
ZeroAppF iles 
MOVEM.L A2-A1,-CSPD 
MOVE.L APPPARMHANDLE, A2 
-HUn lock 
movable (FEA) 
MOVE.L (AØ), A1 
AppParms 
CLR.L (AD 
MOVEQ.L #4,D8 
Se tHandleSize 
MOVEM.L (SP2*,A9-A1 
RTS 
; void SetAppMessage(message ) 
; short message; (DØ) 
Se tAppMessage 
MOVE.L A@,-CSP) 
MOVE.L APPPARMHANDLE,, A 
MOVE.L (A02,A1 
MOVE.W D9,CADD 
MOVE.L (SP2*,A0 
RTS 
; void GetAppNameCappNeme) 
; StringPtr appNeme; 
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; A2 points to count 


; Save into count 


2 


J 


) 
/ 


2 


4 


we we 


we 


we "- o- 


we 


4 


(DØ) 


; restore regs 


; save regs 
; AG points to 


; A2 points to appFile 
; find index 


; if couldn't f ind, 


File 

source ptr 

dest ptr 

put str len in DØ 
mask hight bytes 

if odd number of 
pad with additional 


add space for other 


restore regs 


save regs 
AB points to 


find index 


clear out fType 


restore regs 


save regs 
make sure it's 
Al points to 


message & count to Ø 
set handle size to 4 


restore regs 


save regs 


; Al points to AppParms 
; Move message to app parm area 
; restore regs 


return name of current finder. 


GetAppName 
MOVEM.L A2-A1/D0, -CSP) 
TST.L DØ 
BEQ e1 

return 
LEA CurApName , A8 
MOVE.L D9,A1 
MOVE.B (AØ),DØ 
AND.L #$ØFF,DØ 
ADDQ.L #1,DØ 
-BlockMove 

81 MOVEM.L (SP2*,A0-A1/DO 
RTS 


; GetFndrName(fndrName ) 
; StringPtr fndrName; 


; if string pointer is null, 
; src <- CurApName global 

; dst <- appName 

; get string size 


; edd 1 for size byte 
; copy the string 


(DØ) 


return name of current finder. 


GetFndrName 
MOVEM.L AØ-A1/DØ,-(SP) 
TST.L DØ 
BEQ 81 
return 
LEA F inderName, Ag 


MOVE.L DØ,A1 
MOVE.B CA®),DO 
AND.L  #$ØFF,DØ 
ADDQ.L #1,DØ 
_BlockMove 

e1 MOVEM.L (SP2*,A0-A1/D0 
RTS 

; SetFndrNameCfndrName) 

; StringPtr fndrName; 
set current finder. 


SetFndrName 
MOVEM.L A0-A1/D0,-CSP) 
TST.L DØ 
BEQ 81 
return 
MOVE.L DØ,Að 
LEA FinderName,A1 
MOVE.B (AØ), DØ 
CMP.B #15,DØ 
BGT e1 
AND.L — "$0FF,D0 
ADDQ.L 81,00 
-BlockMove 
81 MOVEM.L CSP2*,A0-A1/D0 
RTS 


; FindIndex 


; if string pointer is null, 


; src <- FinderName 
; dst «- fndrName 
; get string size 


; add 1 for size byte 
; copy the string 


(DØ); 


; if string pointer is null, 

; src <- fndrName 

; dst <- FinderName global 

; get string size 

; if string to big, do nothing 


; add 1 for size byte 
; copy the string 


finds the nth AppFile record. 


pointer to AppFile data or Ø if not found 


; save regs 
set result to 9 
test for legal index 


we We 


; start of first 

; D1 is loop counter 
; index from Ø 

; if Ø we are done 

; Stert of filename 
; 02 gets filename 


mask off high bits 


we 


; INPUT: 
3 AQ .L pointer to AppParms 
; D .W index C1..count) 
; OUTPUT: 
; A1.L 
FindIndex 
MOVEM.L A2-A4/D1-D2, -CSP) 
MOVE.L @,A1 
TST DØ 
BLE FindXit 
CMP 2(A0),D0 
BGT FindXit 
LEA 4(A0),A2 
AppFile 
MOVE D0,D1 
ei SUBQ #1,D1 
BEQ e2 
ADD.L — 88,42 
string 
MOVE.B (A2),D2 
size 
AND.L — "$0FF,D2 
ADDQ.L #1,D2 


; plus one more for 
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size byte 
BIST #9 ,D2 test for pad byte 
BEQ e3 if odd count, we 


we We 


ø 
256 
type DITL 


must pad , 206 


ADDQ.L #1,D2 , &dd one for pad byte 7 
e3 ADD.L 0D2,A2 , edd string size to BtnItem Enabled 
eddress 124 208 144 289 
BRA e1 GOTCHA ! 
@2 MOVE.L A2,A1 ; Store in result StatText Disabled 
FindXit MOVEM.L (SP)+,A2-A4/D 1-D2 ; restore regs 7 91 23 299 
RTS The Front Man... 
#endasm StatText Disabled 


36 10 52 294 

You cen select any number of files using 
StatText Disabled 

52 10 68 294 

the standard file dialog. All of these f iles 
StatText Disabled 

68 10 84 294 

will be passed at once to the application 
StatText Disabled 

84 10 108 294 

to be printed when you select "Launch" 
StatText Disabled 

100 10 116 294 

from the f ile Menu. 


eee 


; Icon Signature for The Front Man 
; Frank Alviani 
; 9:33:17 AM 6/6/86 


[***F**** end of FinderParms.asm **xxeceoeeo /- 


; Link file for The Front Man 
; Frank Alviani 

; 4:87:32 PM 6/4/86 
/NoAnimate 

/Output The Front Man 

/Type 'APPL' 'FEA1' 

/Bundle 

/Start AltStart 

Standard Library.re] 

Front Man.rel 

FinderParms.re] 

/Resources 

Front Man Sig.rel 

/include Front Man.rsrc 

/end 


Resources for The Front Man „ALIGN 2 l 

* Frank Alviani RESOURCE ‘ICN®' 128 'AN ICON' 
* 8:56:46 AM 6/6/86 ; Icon definition 
RomRef DA:Rels:Front Man.rsrc DC.L $00 TFFFF0,$004000 10, $0 1FFFFDO,, $0 1000050 
TYPE MENU DC.L $O7FFFF5O, $04000 150, $05000550 ,$04000 150 

2 DC.L $05160550,$04000 150, $05 184550, $04000 150 
File DC.L $05 100550, $04000 150, $05 1F4550, $04000 150 
Pick/P DC.L $05 100550, $04000 150, $05000550 ,$04000 150 
Launch/L DC.L $FFFFFFFF , $90000049, $FFFFFFF9, $90000049 
Quit/Q DC.L $9FFFFFC9,$80000009, $FFFFFFF9,$8000000F 
* --Configuration Strings-- DC.L $80000008,$90000008 ,$80000008 ,$FFFFFFF8 


X #256: names the application to be launched ; Mask definition 


* #257: if it contains 'ASK' use SFGetFile for APPL name DC.L  SOOIFFFFO, SODTFFFFO, $0 IFFFFFO, $2 IFFFFFO 
* #258: if it contains ‘PRINT’ set message parameter to 1, er villas o cU QUSS udis, 
else Ø C'open') i , ) "3 : 
* 8259: if it contains 'TEXT' only those display, else all a A daaa Dnata a 
ee i DC.L  $FFFFFFFF,$FFFFFFFF, $FFFFFFFF $FFFFFFFF 
256 DC.L —— $FFFFFFFF,$FFFFFFFF,$FFFFFFFF, $FFEFFFFF 
ledit MN $FFFFFFF8, $FFFFFFF8, $FFFFFFF8, $FEFFFFFS 
ie RESOURCE 'BNDL' 128 'BUNDLE' 
258 DC.L 'FEAI' ; NAME OF THE "SIGNATURE" 
Print DC.W 0,1 ; JUST SOME DATA -- DOESN'T CHANGE 
259 DC.L 'ICNW' ; ICON MAPPINGS 
m DC.W Ø ; NUMBER OF MAPPINGS -1 
* "About Box" DC.W 9, 128 ; MAP Ø TO ICON 128 
type DLOG DC.L 'FREF' ) FREF MAPPINGS 
EE DC.W Ø ; NUMBER OF MAPPINGS -1 
‘ DC.W 0,128 > MAP Ø TO FREF 128 


RESOURCE 'FEA1' Ø 'IDENTIFICATION' — 
DC.B 34,'The Front Man - F. Alviani 6/5/86' Sel 
RESOURCE 'FREF' 128 'FREF 1' 

DC.B 'APPL',0,0,0 LLLA 


108 100 250 400 
Visible NoGoAway 
1 
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ABC's of C 
A Print Window for Debugging 


In the first column we did the traditional first C program 
and wrote "hello, world" on the screen using the C function 
printf(). Since then we have examined some C programming 
concepts and gotten a window and menus to appear on the 
screen. Beginning with this column we are going to spend 
some time writing to a window. I am going to start by 
writing some text. My main reason for wanting to start with 
text is the complaint I had with the LightSpeed C compiler: 
there was no way to write to the screen and still see the menus 
and window you put there. Since one of the most useful 
debugging tools is the ability to print out the value of 
variables and to get some indication of where you are in a 
program, I thought a useful and instructive function to write 
would be a printf()-like routine that would not take over the 
entire screen. I called the function printw() (print to window), 
and it turned out to be fairly complex and include some rather 
obscure C. It is not that important if you don't follow the 
entire explanation. There is a lot of standard C presented in 
this month's column, and the function will prove to be quite 
useful. Type it in and get it working. By the way, it is not 
finished, and we will add to it in subsequent installments. 


C Text Conventions 


C compilers provide an escape mechanism in text to 
allow the placement of non-displayable characters inside a 
string. The escape character is the backslash (N. Certain 
characters preceded by the backslash result in a control 
character. Note that the control character is placed in the 
string replacing the backslash and the following character. 
These sequences are referred to in The C Programming 
Language as character constants. 


Sequence ASCII Description 


An LF line feed 

\t HT horizontal tab 
\v VT vertical tab 

\b BS backspace 

\r CR carriage return 
\f FF form feed 

\" double quote 

V single quote 

\\ backslash 


To use these, just place the sequence where you wish to 
have the character: 


char C; 
char *s; 
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Bob Gordon 
Apropos Publications 
Contributing Editor 


File Edit Window ILS! 


v" ep ete y Ty e Tw e ee ee ew T a y y e Ta y Tu v e ee eT e ST 


In 
In MenuBar 65535 -1 
In MenuBar 65535 -1 
In MenuBar 65535 -1 
In content 700000 10 In Desk 10 123 -456 
n MenuBar 65535 -1 


Fig. 1 Our printw() window is out of the way 


c= '\b'; 
S = "\nhello, world\n"; 


Our debug windew! 


You may also follow the backslash with one to three 
octal (octal!) digits to generate any arbitrary character. You 
will most often see \O' which is the null character. 


Loops 
Except for the event loop, we have not had much reason 
to use loops so far. This month, however, there are two 
functions that scan through strings, and I have used two C 
looping constructs. 


To have a loop that tests before the code is run, use the 
while loop. 


while Cexpression ) 
statement 


The expression may be any C expression. If the expression is 
true (non-zero), the statement is executed. If the expression is 
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false (zero), the loop is terminated and the expression is not 
executed. 

A second type of loop tests at the bottom. This means 
that the body of the loop is executed at least once. 


do 
statement 
while Cexpression ); 


In both these loops the statement may consist of any number 
of C statements surrounded by braces ({}). 


Pointers 


It is often necessary to loop through strings. Remember 
that a C string is an array of bytes terminated by the null 
character (NO). A string (or an array) is usually accessed as a 
pointer. For example, given this declaration: 

char S[20];  /* an array of twenty bytes */ 


Assume S is a string with a terminating null character. We 
could loop through s by: 


while (s[i]) 
or 
while (*s) 


The first form uses an index to access each byte or character. 
The second uses the name of the array by itself as a pointer. 
The name of an array is the address of the element zero. The * 
uses the contents of the pointer and accesses that address to 
retrieve the value stored there. In our example, s[0] equals *s. 


The other operator heavily involved with pointers is the 
address of operator, &. This returns the address of any object. 


short X; /* declare x as a short */ 
short *px; /* px is @ pointer to a short */ 
px = &x; /* assign address of x to px */ 


We have used the address of operator when passing structures 
to toolbox functions. 


Pointer Arithmetic 


C knows the size of the object to which a pointer points, 
so it can handle the process of pointing at the next (or 
previous) object automatically. If px is a pointer, px += 1 
increments px by the size (in bytes) of the object to which px 
points. If px points to a structure containing 72 bytes, px += 
1 adds 72 to the current value of px. 

At this point, I should introduce two additional and rather 
unusual C operators. Since incrementing and decrementing are 
done so often, C has special operators for these operations. 


+t+px ; 
“=X; 


/* increment px */ 
/* decrement px */ 
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These are unary operators. What is unusual about them is that 
they may be placed before or after the variable, and the 
placement affects when the operation is carried out relative to 
the variables use in an expression. If placed before the 
variable, the increment (or decrement) operation is done before 
the variable is used. If placed after, the increment/decrement is 
done after the variable is used. 


short x, Y, Z; 
x = 5; 

y = tx; 

x = 5; 


Z xtt 

In both cases above, x ends up equal to 6. In the first, y 
is also six, but in the second z is five as the variable, X, is 
used and then incremented. In many cases it does not matter 
which you use, but when it does matter, it is a likely source 
of problems. The notation is often used because it is compact 
and may result in very efficient code, depending on the 
compiler. The increment and decrement operators work 
correctly with pointers: they increment or decrement by the 
size of the object to which the pointer points. 


Writing to a Window 


The other point of this month's column was to start 
using some QuickDraw functions to write to the screen. I 
only needed DrawChar() and DrawString() to get text on the 
screen. You will also note a call to ScrollRectQ, but it is 
being used in a very simple way, and I think it would be best 
if we pretend it isn't really there this month. 

What is important to note about writing to the screen is 
that all writing takes place in objects called GrafPorts. A 
GrafPort is a complex structure that contains all sorts of 
information about the environment that the QuickDraw 
routines will use. In general you need not worry about the 
individual members of the GrafPort structure as there are 
functions that provide access to them. Only one GrafPort is 
active at a time: the QuickDraw routines do not have a 
parameter that specifies which GrafPort to use; they use the 
one indicated by SetPort(). This is done near the beginning of 
printw(). printw() also obtains the current GrafPort and 
restores it when it is done. 

The Macintosh Toolbox with C book has a couple of 
pages describing how to create and dispose of a GrafPort. 
What they do not make clear is that by creating a window you 
have created a GrafPort. If you examine the window structure, 
WindowRecord, you will see that the first member is a 
GrafPort and that a WindowPtr is a GrafPtr which is a pointer 
to a GrafPort. So if you have a window, you have a GrafPort, 
and you can draw to it. 


This Month's Program 
This month's program is last month's program [See 
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August 1986, issue of MacTutor. -Ed] with the addition of 
two functions: printw() and ntoa(). I placed calls to printw() 
inside domouse() just so I could have printw() work under 
something I could control. At the moment it does not print 
out anything interesting, but you can use printw() to examine 
a variety of variables in the program. Since most of the 
program is exactly the same as last month's, I am going to 
discuss only the two new functions. 

As we all know, one of the problems with using C on 
the Mac is the incompatibility between C strings and Pascal 
strings. These functions use C strings so you can use them in 
your program without any special worry. printw() does any 
necessary conversions to Pascal strings before it calls Toolbox 
routines. 

ntoa() 


ntoa() converts numbers to ASCII. It is a fairly general 
purpose routine that handles signed or unsigned numbers and 
shorts and longs. It begins by checking for signed values. If 
the variable is signed, it converts it to its absolute value and 
sets a flag. Then there is a while loop that mods and divides 
to convert the number to ASCII. It stops when the number 
goes to zero. At this point the number has been converted but 
it is in the string backwards. A do-while loop is used to copy 
the string into the correct order. Finally, the null character is 
put on the end of the string. 

One thing to note is the variable i. It is initialized when 
it is declared. Automatic and register variables have garbage 
values until they are initialized either in code or when they are 
declared. The effect of initializing an automatic variable is the 
same as setting its value in the code, but sometimes it is 
clearer to use initialization. Also note the use of casts to 
convert the value to the correct size. There will be more on 
this in the discussion of printw(). 


printw() 


This routine contains a certain amount of C esoterica. If 
you are not interested in how C handles parameters, feel free to 
skip this discussion. On the other hand, the routine should 
prove quite useful, and it does follow the tradition established 
in Kernighan and Ritchie of learning C by examining standard 
C functions. 

printw() mimics the standard C library function printf(). 
printf() prints to the "standard output device" and can take a 
variable number of parameters. printw() prints to its own 
window and also can take a variable number of parameters. 

One parameter is required in printf() (and printw()), the 
control string. This is a string that is printed and may contain 
a variety of conversion specifications. These have varying 
complexity and can specify justification, the type and size of a 
variable to be printed, the width of the field in which to print, 
and whether the variable is signed or unsigned. Each 
specification starts with a percent sign (96) and ends with a 
conversion character. printw() provides a limited subset of 
these: 
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d decimal 

u unsigned decimal 

c  asingle character* 

S  astring* 

x unsigned hexadecimal* 
*Not yet implemented. 


You may place a lower case ] (T) before the u or d to 
indicate the variable is a long rather than a short. 

As printw() prints to its own window, the first time it is 
called it creates the window. The window is set at the bottom 
of the screen. This is hard coded in the call to SetRectO; 
change the position or size as desired. In fact it might be 
useful to have a code in the control string that allows the 
rectangle to be defined on the fly. To know whether or not the 
window has been created, it checks the value of pw, the 
WindowPtr. This is a static variable (static variables retain 
their values between calls), and actually C guarantees that all 
statics will be initialized to zero. If pw is zero, the window 
does not exist so it is created. C also guarantees that no legal 
pointer will have a value of zero, so we know the value 
returned by NewWindow() will be non-zero. 

I used GetFontInfo() to retrieve the line size. Since this 
does not change, the computation of line size could be moved 
inside the window opening code. 


Parameter Passing 


C generally passes parameters on the stack. LightSpeed 
C does this. Mac C passes parameters in registers if it can, 
however you can force it to pass parameters on the stack if 
you need to. Mac C also has a special, non-standard way of 
indicating that a function will receive a variable number of 
parameters. See note at the end. 

As the LightSpeed C manual points out, the parameter 
passing conventions are a de facto standard so what follows 
may not apply to your compiler. When a function is called, 
the parameters are placed on the stack from right to left: 

afunc(a,b,c,d); /* call of afunc() with four 
parameters */ 


Picture of stack 


Yoon a 


SP---) eturn address 

As illustrated, d is pushed first, then c, and so on 
(remember, the stack grows down in memory). This means 
the first parameter (a) is the last one placed on the stack and is 
in a known position just above the return address. If the first 
parameter contains information about the number of 
parameters passed on a call, we can write a function that can 
handle a variable number of parameters. Unlike Pascal, the 
process of cleaning up the stack after the call is handled by the 
caller. Since the caller knows how many parameters were 
passed (or where the stack pointer was before the call), the 
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stack can be correctly maintained. printf( and printw() use the 
percent signs in the control string to determine the number of 
parameters passed. 

The problem now is to determine where the parameters 
are. The control string is passed as a pointer. That is, we 
have the address of the string. What we need is the address of 
the pointer (the parameter). This is obtained by using the 
address of operator in the line: 


ts = ks; 


ts is now a pointer to a pointer to a string. This is converted 
to a ordinary pointer with a cast on the next line. Finally, we 
add the size of a pointer to the value to leave us pointing at 
the second parameter on the stack. 


Back to printw() 


The major portion of printw() is a case statement that 
examines every character in the control string. If the character 
is not a new line or a conversion character, it is drawn in the 
window (with DrawChar()). If it encounters a new line (\n), it 
determines if it should scroll the window or not and moves the 
drawing position to the beginning of the next line. This is 
where the line size, computed at the beginning of the function, 
is used. If it finds a percent sign, it begins to determine the 
kind of parameter. 

I think most of the code is fairly straightforward. When 
the a y or d conversion character is detected, it must extract a 
number from the parameters. At this point we know if the 
number is a long or not (having previously detected an 'l' if it 
is to be a long). Since we have a pointer to a char instead of a 
parameter, a cast is used to obtain the correct size number. 


num = *(ulong*)ps; 


ps is a pointer to a character. The cast (ulong*) converts it to 
a pointer to an unsigned long (ulong was added to abc.h), and 
the '*' to the left of the cast dereferences the pointer to obtain 
the value. Note that the variable num is an unsigned long 
which is what ntoa() expects. 

Another less obvious construction is in the call to ntoa(). 
ntoa() receives four parameters one of which is a flag 
indicating whether the value is signed or not (it is True if 
signed). The call to ntoa() contains 


'u' c *s 


for the signed parameter. If the conversion character (*s) is a 
'u, this results in a value of zero or False, if it is a 'd,' it will 
be non-zero and True. 

Also note that each time we extract a parameter we 
increment the parameter pointer, ps, by the size of the 
parameter. This is an excellent place for the code to get 
confused. 


Note for Mac C 
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To create a function that deals with a variable number of 
parameters Mac C uses a special construct. The last parameter 
in the function must be "..." as in: 


int printfCformat, arg, ..) 


If the routine is external (not included in the file in which 
it is called), it must be declared: 


extern int printf(..); 


Another difference in Mac C relevant to printw() is the 
interpretation of the \n character. LightSpeed C (and standard 
C) interpret the \n as a line feed; Mac C translates it to a 
carriage return. This should pose no problem if you use the 
\n' consistently. 

Refer to Appendix A of the Mac C Programmer's Guide 
for details. 

A Problem 


In the domouse() routine that passes control to different 
routines depending on where the mouse is, there are a number 
of printw() calls. They are there simply to have something 
print out. Also in this routine is a change from last month's 
program caused by the addition of the printw(). If the mouse 
is in the window content area, it may be in the printw() 
window or some other window. We normally would be 
interested only in the other window. I added an if-statement 
here to ensure response only if in the correct window, but this 
is not a very good solution. Another solution would be to 
declare the pointer to the printw() window as a global and 
check that the mouse is not in that window. A third 
possibility would be a function that checks for the printw() 
window. Perhaps the best would be a replacement for 
FindWindow( that could check for the printw() window. This 
way when it came time to remove the printw(), you could 
simply link in the correct version of FindWindow(). 


Current Version of abc.h 


/* abc.h 

x 

* Local definitions to improve readability 
x 

27 


#def ine True 
"define False 
#define Nil 

#def ine and && 
"idefine or 
"define not 
8define equals 
def ine notequal 


Q OQ — 


/* unsigned longs and shorts 

* (unsigned longs may not be 

* available with 811 compilers */ 
8define ushort unsigned short 
"define ulong unsigned long 
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/* General purpose external routines 
* String conversion routines 

* return a pointer to a char 

*/ 


*CtoPstr(); 
*PtoCstr(); 


Program with printsC) 


extern char 
extern char 


/* Sending text to window with 
* function that accepts a variable 
number of parameters 


* 


x 

* Compiled with LightspeedC 

* Note L8 puts 'Mgr' in h file names! 
* (load MacTreps into the project first.) 
*  [mportent note for Mac C users: 

x Every place you see event-»where, 

x replace it with &event-— where 

*/ 

"include “abc.h" 

include — "Quickdrew.h" 

*Sinclude X "EventMgr .h" 

include — "WindowMgr .h" 

include X "MenuMgr.h" 


/* defines for menu ID's */ 


define Mdesk 100 
#def ine Mfile 121 
tdef ine Medit 102 
#def ine Mwind 193 
“define Mtest 104 


/* Global variables */ 


MenuHandle menuDesk; /* menu handles */ 

MenuHandle menuF ile; 

MenuHandle menuEdit; 

MenuHandle menuWind; 

MenuHandle nenuTest; 

WindowPtr theWindow; 

WindowRecord windowRec; 

Rect dragbound; 

Rect limitRect; 

nainC) 
initsysC); /* system initialization */ 
initepp(C2; /* application initialization */ 
event loop(); 


/* system initialization 

x note use of hard coded screen sizes 
x with LightspeedC. This will work 

x with other compilers but is not 

x good practice 


=] 
Ce 
InitGrafC&thePort); /* these two lines done */ 
InitFonts(); /* automatically by Mac C */ 
InitWindows(); 
InitCursor(); 
InitMenus(); 
theWindow = Nil; /*indicates no window */ 
SetRect(&dragbound,8,8,512,258); 
) SetRect(&limitRect,60,40,508,244); 
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application initialization 
Sets up menus. 
Each menu is a separate group 
of lines. Note the last menu 
is appended but not inserted. This 
makes it part of the menu list but 
not in the menu bar. 


ce 


) 
/* 


x 
x 


menuDesk = NewMenu(Mdesk, CtoPstr("\24")); 
AddResMenu CmenuDesk, ‘DRVR'); 
InsertMenu CmenuDesk, Ø); 


menuFile = NewMenuCMf ile, CtoPstr("File")); 
AppendMenu (menuF ile, 

CtoPstrC"Open Window/M;Close Window/X;Quit/Q")); 
AppendMenu (menuF ile, 

CtoPstrC"C-;Show Test; (Hide Test")); 
InsertMenu (menuFile, Ø); 


menuEdit = NewMenuCMedit, CtoPstrC"Edit")); 
AppendMenu CmenuEdit, 

CtoPstr( "Undo; (-;Cut;Copy;Paste;Clear")); 
InsertMenu (menuEdit, 9); 


menuWind = NewMenuCMwind, CtoPstrC"Window"2); 
AppendMenu CmenuWind, 

CtoPstrC"Hide;Show;New Title")); 
InsertMenu CmenuWind, 9); 


menuTest = NewMenu(Mtest, CtoPstr("Test")); 
AppendMenu (menuTest, 

CtoPstrC"Pick;0ne;0f ; These" )); 
DrawMenuBarC); 


Event Loop 
Loop forever until Quit 


rs 


+] 


EventRecordtheEvent; 
char C; 

short windowcode; 
WindowPtr WW; 


whi leCTrue) 


if CtheWindow) /* this code is here to prevent 
/* closing en already closed */ 
EnebleItemCmenuFile,2); —/* window! */ 

)o CHEESE RN 


else 


EnebleItem(menuF ile, 1); 
pO ener eae 


if (GetNextEventCeveryEvent,&theEvent2) 
switchCtheEvent . what) 
( /* only check key and */ 
cese keyDown: /* mouse down events */ 
if ne eee & cmdKey) 


c = theEvent.message & 
charCodeMask; 
poen 


break; 


case mouseDown: 
domouse(& theEvent); 
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/* domouse 
* handle mouse down events 
*/ 

domouseCer ) 

í EventRecord*er ; 


short 
WindowPtr 
short 
long size; 

ushort t1 = OxFFFF; 
short t2 = OxFFFF; 


windowcode; 
whichWindow; 


windowcode = FindWindowCer-?where, &whichWindow); 
ia (windowcode) 


case inDesk: 
if CtheWindow notequal 9) 


HiliteWindowCtheWindow, False); 
DrawGrowIconCtheWindow); 


printwC" In Desk Sd $1d £d ", 10, 123L,-456); 
break; 

cese inMenuBar: 
printwC"AnIn MenuBar 3u $d ",t2,t1); 
domenu(MenuSe lect(er->where)); 
break; 

case inSysWindow: 
SysBeep( 1); 
break; 

case inContent: 
printwC"\nIn content 31d 8d", 700000, 700000); 
if Co equals theWindow) 


HiliteWindowCwhichWindow, True); 
DrawGrowIconCtheWindow); 


break; 
case inDrag: 
DragWindow(whichWindow, er-?where, &dragbound); 
DrawGrowIconCtheWindow); 
break; 
case inGrow: 
/* not included this month */ 
break; 
case inGoAway: 
ingo = TrackGoAway(CwhichWindow, er-) where); 
if ta 


CloseWindowCwhichWindow); 
ee = Nil; 


break; 


) 


/* domenu 
x handles menu activity 
* simply a dispatcher for each 
x menu. 
*/ 
domenu(me) 
long mc; /* menu result */ 


short 
short 


menuld; 
menuitem; 
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) 


menuld = HiWord(mc); 
menuitem = LoWord(mc); 


Switch CmenuId) 


cese Mdesk : 
break; /* not handling DA's */ 

case Mfile : 
dof ileCmenuitem); 
break; 

case Medit 
break; 

case Mwind : 
dowind(menuitem); 
break; 

case Mtest : 
dotestCmenuitem); 
breek; 


HiliteMenuC0); 


/* dofile 


x 


* 


handles file menu 


dof ileCitem) 


*/ 


/* 


short item; 


char *titlel; 
Rect boundsRect ; 
idi (item) 


case 1: /* open the window */ 
title! = "ABC Window"; 
SetRect(&boundsRect , 50,58, 300, 150); 
theWindow = NewWindow(&windowRec, 
&boundsRect, 


CtoPstr(title1), True, documentProc, 
CWindowPtr) -1, True, Ø); 

DrawGrowIcon( theWindow); 

PtoCstr(titlel); 

DisableItemCmenuFile, 1); 

EnableItemCmenuFile,2); 

break; 


cese 2 : /* close the window */ 
CloseW indow( theWindow); 
theWindow = Nil; 
DisableItem(menuFile,2); 
Enablel temCmenuF ile, 1); 
break; 


case 3 : /* Quit */ 
ExitToShel1(); 
break; 


case 5 : /* Install additional menu */ 
Inser tMenuCmenuTest,@); 
EnableI tem(menuF ile, 6); 
DisebleItemC(menuFile,5); 
DrawMenuBar C); 
break; 


case 6 : /* remove additional menu */ 
DeleteMenu(Mtest); 
EnableItemCmenuF ile,5); 
DisebleItemCmenuFile,6); 
DrewMenuBar(); 
break; 


/* first title for window 
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*  dowind 

x handles window menu 

x Note that each case contains an 
x if testing the existence of the 
x window. This could be written 
x 


with one if before the switch. 
x 


dowindCitem) 

short item; 

char *title2; /* second title for window 
*/ 


switch Citem) 


case 1: /* Hide */ 
if CtheWindow) 
HideW indow( theWindow); 
break; 
case 2: /* Show */ 
if CtheWindow) 
ShowWindowCtheWindow2; 
break; 
case 3: /* Change title */ 
if M 


title2 = "A Different Title"; 
SetWTitleCtheWindow, CtoPstr(title2)); 


LOSS eee 
break; 
) 
/*  dotest 
x Handles new menu. 
x All this does is mark menu 
x items if they ere not marked and 
* unmark them if they are. 
*] 
dotestCitem) 
short item; 
short mark; 


GetI temMark(menuTest, i tem, &mark); 
if Cmark) 
CheckI temCmenuTest, item, False); 


e 
CheckI temCmenuTest, item, True); 


/* Displays strings and numbers in a 

* special window 

x This function is designed to receive 

x a variable number of parameters. The 

x number is computed by the number of 
percent signs in the control string. 

x If the number of parameters following the 
x control string does not match the 

x number of percent signs, expect 

* the unexpected. 
1 
printw(s) 

char *s; /* the control string */ 

"define Bufsz 14 /* size of buffer to hold */ 
/* converted numbers */ 


static Rect boundsRect; /* variables for */ 

static Rect windowRect; /* defining printw */ 
static WindowRecord wrc; /* window, pw is */ 

static WindowPtrpw = Ø; /* initialized to Ø */ 
WindowPtr oldport; /* save grafport here */ 
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short linesz; /* size of line */ 

FontInfo info; 

short nl; 

Point pt; 

RgnHandle updrgn; /* needed for scrolling */ 
char numAsStr(Bufsz];  /* number conversion */ 
short nsz; /* size of numbers (2 or 4) */ 
char **ts; /* ptr to ptr to ctrl 
string */ 

char *ps; /* ptr to parameters */ 
ulong num; /* for number conversion */ 
short convchar ; /* found conversion char */ 
short islong; /* number is a long */ 


/* Window rectancgle coordinates */ 


"define wl Ü 

"define wr 512 
"define wt 250 
define wb 342 


GetPortC&oldport); /* save current graph port */ 
GetFontInfoC&info); /* compute line height */ 
linesz = info.ascent + info.descent; 
if (pw equals 0) /* if window does not exist*/ 
/* open it */ 
SetRect(&boundsRect,wl,wt, wr , wb); 
pw = NewWindow(&wrc, &boundsRect, 
CtoPstrC""5, True, plainDBox, 
CWindowPtr) -1, True, Ø); 


nl = linesz; /* move down one line as */ 
) /* writing will be above */ 
else /* boundary. No need to */ 

nl = 8; /* move line if open */ 
SetPort(pw); /* Set port to this window */ 
MoveC0,n12); /* Move (relative) */ 
ts - &s; /* get address of control string ptr */ 
ps = (char *)ts;  /* convert to pointer to params */ 


ps += sizeofClong); /* skip over control string 


pointer*/ 


*/ 


while (*s) /* loop until end of control string 


a (*s) /* check each character */ 

case '$' : /* percent sign: check conversion */ 
stt; /* point to next char */ 
convchar = False; /* initialize conv loop 


my 
islong = False; 
do { /* until reach conv char */ 
switch (*s) 
cese ']' : /* indicates a long */ 
islong = True; 
stt; 
break; 
case 'u' /* unsigned decimal */ 
case 'd' /* signed decimal */ 
if P extract number */ 
num = *Culong*Ops; 
"d = sizeof(long); 
else 
num = *Cushort*)ps; 
nsz = sizeof(short); 
ps += nsz; /* point to next param 
*/ 
/* convert number and write it to 
* window 
*/ 
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ntoa(num,nsz,'u' - *s,numAsStr); 
DrewStringCCtoPstr(numAsStr)); 
convchar = True; 
break; 
/* strings, individual chars and hex 
* numbers not handled yet*/ 
case 's' ; 
break; 
case 'c' 
break; 
/* if it is not any expected char, 
* write it out and go on 
x 


default: 
DrewCharC*s); 
convchar = True; 


) while Cnot convcher); 
break; 
case '\n' : /* newline C'An') in control string 
i 
GetPen(&pt); — /* f ind current pen position */ 
if Cpt.v*linesz > wb-wt)  /* if it goes off , */ 
( /* scroll the window */ 
updrgn = NewRgn(); 
ScrollRect(&(pw-» por tRect), ø,- 
linesz,updrgn); 
DisposeRgnCupdrgn); 
Ma RU 


/* no update */ 
/* move onto window */ 


Move(-pt.h, linesz);/* move to next line */ 
break; 

/* any other character gets */ 
/* written on the window */ 


Stt; /* move pointer to next char */ 
) /* in control string and cont*/ 
SetPortColdport); /* restore orignal graf port */ 


wnn ē wM 


* Convert numbers to ascii strings 
x Handles signed end unsigned 
* short and long values 

* Note: Length of string returned 
x must be large enough to 

x hold -26 (12 bytes) 
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*/ 
ntoa(n, len, issigned, s) 
ulong n; /* number to convert */ 
short len; /* size of n (2 or 4)*/ 
short issigned; /* signed flag */ 
char Xs; /* string to return */ 
char ts[12]; /* temporary string */ 
int i = Ø; /* counter, initialized */ 
ulong n; /* working copy of */ 
long sm; /* to convert signed values */ 
if (n equals 0) /* if n is zero, place 'Q' */ 
tslit+] = '0'; /* in temporary string */ 
else 
if Cissigned) /* if sign flag is set, */ 
/* convert to signed value */ 
if (len equals sizeof Clong)) 
sm = Clong)n; 
else 
sm = Cshort)n; 
if Cissigned = sm < Ø)/* Check if value is */ 
n = -sm; /* negative. If so, */ 
/* keep the flag and */ 
/* get the absolute value */ 
while Cn) /* Convert number into ascii */ 
( /* by repeatedly taking mod */ 
ts[it*t102 n $ 10 + '0'; /* and dividing. */ 
n /= 10; /* This gives a string in 
*/ 
) /* reverse order */ 
if Cissigned) /* If number was negative, */ 
" ts[it*12 '-': /* stick a minus sign in 
) /* the string. */ 
do ( /* Reverse the string */ 
*s*t* = ts[--i]; /* to the correct direction*/ 
while Ci); 
¥g = '\'; /* Place null terminator on */ 
) /* string */ 


e 


CORE 


203 


ABC's of C 
Text Display from Quickdraw 


Text Display on the Mac 


Like last month's, this month's column 
deals with using QuickDraw routines for 
writing text to a window. Last month we only 
needed a couple of routines to get printw() 
working; this time I tried to use as many of the 
QuickDraw text functions as I could. [Note that 
Quickdraw is the only way text can be drawn to 
the screen. Ultimately, all programs no matter 
how sophisticated must use Quickdraw to get 
text on the screen. -Ed] 

Those who have been reading along since 
the ABC's of C started will realize we have 
almost covered all of C. This does not mean 
we are done, but does reflect the nature of C as 
a language. C is a relatively small language. 


If you count keywords, for example, it has fewer than many 
dialects of Basic. On the other hand, much of the language's 
capabilities are not in the language itself but are in one or 
another libraries. — Many capabilities included in other 
languages (such as file access and I/O) are in libraries. In 
learning to use C on the Macintosh, the main part of the 
problem is to learn to use the various Toolbox functions. We 
have done menus and started windows. The plan is to now 
follow the chapters in Using the Macintosh Toolbox with C 
and focus on the Toolbox. This will result in a distorted 
view of C, in that we will not generally discuss the standard C 
functions if there is an analogous Macintosh function. 


Short Personal Digression 


You may have noticed the note in the September issue. I 
came down with an exotic, flu-like disease that lasted about 
two weeks and had me bedridden for one of them. It must 
have been reasonably serious because my doctor threatened to 
stick an IV in my arm and put me in the hospital. I 
convinced her that such measures were not necessary and seem 
to have survived. 

But then over Labor Day weekend, my Mac died. I 
stepped out of the room to check on the state of the children, 
and when I returned the screen was dark and there was the 
unmistakeable smell of fried electrons. I quickly turned 
everything off, but it was clear that some component had 
expired. My diagnosis was that the analog board had failed. I 
called around to get estimates for replacing the analog board. 
These ranged from just over $100 to over $200. If you are 
unlucky enough to have your Mac fail, be sure to get 


204 


Bob Gordon 
Apropos Publications 
MacTutor Contributing Editor 


ABC Window 


Fig. 1 Text from Quickdraw 


estimates. I figure I saved $90.00 to $100.00 just by spending 
some time on the phone. 


Text on the Macintosh 


Anyone who has ever seen a Mac realizes that unlike 
conventional computers, the Macintosh displays text in 
different sizes, styles, and fonts. While the Macintosh 
Toolbox contains a set of text-editing functions (TextEdit), 
they are limited to displaying only one font/size/style at a 
time. By directly calling the QuickDraw functions, we can 
display text almost any way we want. In order to do this, I 
first set up menus to allow user control over the font, style, 
and size, and then placed a routine in the event loop to capture 
keys and write them to a window. That is all this month's 
program does. It does not word wrap, scroll, backspace, or do 
any other useful editing operation. 


Text Menus 


Like the Desk Accessories, the font menu is acquired with 
AddResMenu(). AddResMenu() searches resource files for 
resources of the type specified and appends them to the menu. 
So only two lines are needed to create the font menu: 


menuFont = NewMenu(Mfont), CtoPstrC"Font")); 
AddResMenu CmenuFont, 'FONT'); 


This creates the menu, but a program cannot use the 
information directly. The program needs to be able to use the 
font number that identifies the font. When a user pulls down a 
menu and selects an item, the program receives a number 
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indicating which menu and which item. Since the program 
has no idea of the available fonts or their position in the 
menus, we need a way to determine the font number from the 
item number. Two functions accomplish this. The first 
Supplies the item text given the number, and the second 
Supplies the font number given the font name. These 
functions are called in dofont(): 


GetItem(nenuFont, item, &itemS); 
GetFNum(&itemS, &cfont); 


The parameter itemS is a Pascal string. There is no need 
to call CtoPstr() because both routines are from the Toolbox 
and both expect Pascal strings. cfont receives the font number 
which is passed to the editor routines with ed cset(). (I am 
taking the liberty of calling them editor routines even though 
they do no editing. Perhaps someday they will.) 


The operation of the size menu is simpler. The sizes 
displayed in the menu are 9, 10, 12, 14, 18, 24, 28, and 36 
points. To get the correct size from the menu item, a global 
array called sizes is initialized to those values. In C, all arrays 
Start at zero so the zero element is not used, at least not 
directly from the menu. You will note it is initialized to 8 
points. One of the styles supported is "Small Caps," and the 
8 point size is used to make small caps for the 9 point size. 


One of the features of size menus is that they let the user 
know which sizes are available and which must be scaled. 
This varies with the font and so is included in dofont(. A 
function from the font manager, RealFont() returns a true 
value if the font in a given size actually exists. The following 
little loop provides this feature. 


for Ci = 1; i < Nsize; i++) 
if (RealFontCcfont, sizes[i12) 
SetItemStyleCmenuSize, i, Out] ineStye); 
else 


SetI temStyle(menuSize, i, ð); 


This also shows a for loop. The statement consists of 
five components: 


for € initialize ; test ; increment ) 
statement; 


This directly translates into the following while loop: 


initialize; 
mee test ) 


statement; 
increment; 


This translation shows how the loop is constructed. The 
initialization takes place once before the loop begins. The test 
occurs at the top of the loop, and the increment at the bottom. 
The primary advantage of using a for over a while is that all 
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the loop components are available on one line. You may 
omit any of the components on the for line but the 
semicolons must be there as place holders. 

It is also possible to have several statements in the for: 


for Ci = 8, j =O; i « 10; i++, j++) 
statement; 


Commas separate statements within each line section. 
_ The final text menu handles the style. I have included all 
the styles I have seen, which include: 


Plain 

Bold 

Italic 
Under ine 
Outline 
Shadow 
Condensed 
Extended 
Small Caps 
Superscript 


Subscr ipt 


The first eight are standard Macintosh styles; the others 
are in MacWrite or Word. As anyone familiar with the Mac is 
aware, the styles generally may be combined. I assumed that 
it makes no sense to combine Condensed and Extended or 
Superscript and Subscript. This complicates the menu arrange- 
ment a bit, as selection of an item does not mean just setting 
or removing a check mark. The total style is collected in a 
short, in which each bit represents one style. Since only ten 
bits are in use so far (Plain is all bits off) suggestions for 
additional styles are open (would it, for example, be nice to set 
a block of text to all upper case or lower case as in 
MacDraw?). Where possible, the style menu illustrates the 
style through the use of the menu meta-characters. 


Getting the Text 


The eventloop() detects keyDown events. If the 
command key is not down, it calls ed key() to send the 
character to the window. The event loop does not call 
ed key() unless the window has been opened to prevent 
writing to an unopened window. At the moment it does not 
detect auto-key events. This would be something to add. 


The Edit Functions 


There are several Edit functions, but only two of them are 
of real importance. Two, ed init() and ed new() do some 
simple initialization. For this program they probably could 
have been combined. The most important thing that ed new() 
does is to call each of the text-setting functions, dofont(), 
dosize(), and dostyle(, to establish initial conditions and set 
the menus accordingly. Each of those functions contains 
special code to handle the situation where the item equals zero. 
Since the item cannot equal zero when it is the result of 
mouse input, I used it for initialization. 
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Any time there is a change in font, size, or style, the 
relevant function calls ed cset() where the change is noted and 
stored. ed_cset does not effect the change; it just keeps it 
around. This allows users to change their minds by making 
repeated changes through the menu without affecting anything. 
The change is put into effect when ed key() is called from the 
event loop. 

The function ed. key() does most of the work. It calls the 
various QuickDraw routines for changing font, size, and style, 
uses DrawChar() to write the character. For each kind of 
change it checks the flag in edbuf.cesc, and if the flag is set, it 
gets the value and does the change. 

The styles not built into QuickDraw require special 
handling. To deal with the super and subscripts, ed key() 
retrieves the pen position and adjusts it vertically. It does this 
for every character written. It probably could be done only 
when the the styles involved changed, but this logic is 
simpler. 

Prior to writing each character, ed key() checks if small 
caps is on. If it is, and the character is a lower case letter, it 
sets the size to the next smaller size (in the menu), converts 
the character to upper case, draws it and sets the size back to 
the original size. The actual character itself is not affected. 
Two library functions, islower() and toupper(, provide the test 
of lower case and change to upper case. These are part of a set 
of character functions that most C compilers include. I have 
not used the library, but included the functions right in the 
program. This is not due to any aversion to using libraries, 
but because the functions in the Lightspeed library use a C 
construct we have not used before: 


toupper(c) 
cher c; 


returnC os'a')&&Cc«c'z') ? (c-32) : c); 


This construction may be read: 


test ? do if true : do if false 

As can be seen in toupper(), this form can be rather 
cryptic at first. toupper() simply asks if the character, c, is 
greater or equal to ‘a’ and less than or equal to 'z.' If it is, 
subtract 32 (converts to upper case in ASCII) and return that 
value; if not, return c unchanged. 


Organization of the Program 


The edit functions are in a separate file, and there is a 
separate header file, ed.h, that is included in the main program 
and in ed.c. 

You will notice several lines in ed key() that serve no 
apparent purpose. The structure edbuf contains a buffer in all 
characters and font/size/style changes are written (though the 
line that writes to the buffer is commented out). This is to 
allow eventual updating of the window. 
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printw() 


There have been two changes to printw(). First, I fixed a 
bug. Previously it determined the line size on each call from 
the Grafport that was open when it was called. This resulted 
in rather odd interaction between the window being written by 
ed keyQ, the printw() window and the menus. At one time I 
had menus with text in one or two point type. I moved the 
determination of line size inside the if-statement that is done 
the first time printw() is called. 

The other change is the addition of code to print strings. 
This prints only C strings. We probably should add the 
ability to print Pascal strings and points and rectangles. Some 
of these changes may happen for next month. 


Next Month 


I hope to get my Mac upgraded with the 128K ROMs and 
the 800K drive. I also hope to stay healthy. We will 
continue to explore QuickDraw. I intend to draw various 
shapes on the screen. 


QD1.C 

Sending text to window with 

function that accepts a variable 
number of parameters 


— 
A 9 9 »* MH x MH »* »* MH x* 


— 


Conpiled with LightspeedC 


Important note for Mac C users: 
Every place you see event-?where, 
replace it with &event-) where 


include "ebc.h" 
include "Quickdraw.h" 
8include "EventMgr .h" 
8include “WindowMgr .h” 
*include "MenuMgr .h" 
8include "FontMgr .h" 
*include "ed.h" 


/* defines for menu ID's */ 


"def ine Mdesk 100 
#def ine Mfile 101 
def ine Medit 102 
def ine Mfont 183 
def ine Mstyl 104 
define Ms ize 105 
/* Window items */ 

/* File */ 

define iNew 1 

#def ine iClose 2 

8def ine iQuit 3 

/* Edit */ 

define iUndo 1 
define iCut 3 
"define iCopy 4 

"def ine iPeste 5 

/* Style */ 

"def ine iPlain 1 

"def ine iBold 2 
define iItalic 3 

"def ine iUline 4 
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"define i0line 5 

"def ine iShado 6 

"def ine iCon 7 

#def ine iExt 8 

"def ine iScaps 9 

def ine iSuper 10 
"define iSub 11 
"define PlainStyle ø 
8def ine BoldStyle 1 
#def ine ItalicStyle 2 
"idef ine UnderStyle 4 
8def ine OutlineStyle 8 
"gef ine ShedowStyle 16 
"define CondStyle 32 
"def ine ExtStyle 64 


/* Global variables */ 


MenuHandle menuDesk; /* menu handles */ 

MenuHandle menuF ile; 

MenuHandle menuEdit; 

MenuHandle menuFont; 

MenuHandle nenuStyl; 

MenuHendle nenuSize; 

WindowPtr theWindow; 

WindowRecord windowRec; 

Rect dregbound; 

Rect linitRect; 

"define Nsize 9 

uchar sizes(Nsize] = (8,9, 10, 12, 14, 18, 24,28, 36); 

iin 
initsys(); /* system initialization */ 
initappC); /* application initialization */ 
eventloop(); 


/* system initialization 
* note use of hard coded screen sizes 


x with LightspeedC. This will work 
x with other compilers but is not 

x good practice 

*/ 

Coen 


InitGref(&thePort); /* these two lines done zJ 
InitFonts(); /* automatically by Mac C */ 
InitWindowsC); 

InitCursor(C); 

InitMenusC); 

theWindow = Nil; /*indicates no window */ 

Se tRect(&dragbound, 0,0,512,258); 
SetRect(&1initRect,60, 40,508,244); 


/* 

* application initialization 
s Sets up menus. 

x Initialize ed 

*/ 

Coe 


se tupmenuC ); 
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ed initC); 
/* 
* set up epplication's menus 
x Each menu is a separate group 
x of lines. 
*/ 
Ce 


menuDesk = NewMenuCMdesk , CtoPstr("\24")); 
AddResMenu CmenuDesk, "DRVR' 5; 
InsertMenu (menuDesk, Ø); 


menuFile = NewMenu(Mf ile, CtoPstrC"File")); 
AppendMenu (menuF ile, CtoPstr("New;Close;Quit/Q")); 
InsertMenu (menuFile, Ø); 


menuEdit = NewMenuCMedit, CtoPstrC"Edit"2); 
AppendMenu (menuEdit, CtoPstr( "C(Undo/Z; C- 


;(Cut/X; CCopy/C; CPaste/V; (Clear "5; 


)); 


InsertMenu (menuEdit, Ø); 


menuFont = NewMenu(Mfont, CtoPstrC"Font")); 
AddResMenu (menuFont, 'FONT ' 5; 
InsertMenu (menuFont, 0); 


menuSty] = NewMenu(Mstyl, CtoPstrC"Style")); 
AppendMenu CmenuStyl, 
CtoPstrC"Plain/P; <BBold/B; «IItelic/I; «UUnder1 ine/U; " 


AppendMenu CmenuStyl,CtoPstr( 


"<00ut 1 ine /0; «SShadow/S; Condensed; Extended" 2); 


AppendMenu (menuSty1, CtoPstr( 


"SnallCeps ;Superscr ipt /H;Subscr ipt/L" 2); 


InsertMenu CmenuStyl, 9); 


menuSize = NewMenu(Msize, CtoPstr("Size")); 
AppendMenu (menuSize,CtoPstr( "09 Point; 18 Point; 12 


Point; 14 Point")); 


AppendMenu (menuSize,CtoPstr( "18 Point;24 Point;28 


Point;36 Point")); 


InsertMenu (menuSize, Ø); 


DrewMenuBar (C); 
/* Event Loop 
* Loop forever until Quit 
x 
Coe 
EventRecord theEvent; 
char C; 
short windowcode; 
WindowPtr ww; 
whi leCTrue) 


if i i /* this code is here to */ 


/* prevent closing an already */ 
EnableItem(menuFile,2); /* closed window x/ 
y RIR emer tes, 
else 


( 


Enablel tem(menuF ile, 1); 
DisableItemCmenuF ile, 2); 


if CGetNextEventCeveryEvent, &theEvent)) 
SwitchCtheEvent . what ) 
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/* domouse 
x 


( 


case keyDown: 


/* only check key and */ 
/* mouse down events */ 
c = theEvent.message & charCodeMask; 


if CtheEvent modifiers & cmdKey) 
domenuCMenuKeyCc2); 
else if CtheWindow) 
ed_key(c); 
break; 
case mouseDown: 
domouse(& theEvent); 
break; 
default: 
break; 


handle mouse down events 


domouse Cer ) 


( 


) 


EventRecord žer; 


short windowcode ; 
WindowP tr whichWindow; 
short ingo; 

long size; 

long newsize; 


windowcode = FindWindowCer-?where, 


&whichWindow); 
Switch Cwindowcode) 


case inDesk: 
if CtheWindow notequal 2) 


HiliteWindowCtheWindow, False); 
p eem 


break; 

case inMenuBar : 
domenuCMenuSe lect Cer-> where) ); 
break; 

case inSysWindow: 
SysBeep( 1); 
break; 

case inContent: 
if CwhichWindow equals theWindow) 


HiliteWindowCwhichwWindow, True); 
p ren 


break; 
case inDrag: 
DregWindowCwhichWindow, 
er-)where, &dragbound); 
DrewGrowIconCtheWindow); 
break; 
case inGrow: 
break; 
cese inGoAway: 
ingo = TreckGoAwayCwhichWindow, er-> where); 
if Cingo) 


CloseWindow(whichWindow); 
ii = Nil; 


break; 


/* domenu 
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x 
x 
x 


*/ 


domenu(mc) 


( 


handles menu activity 
simply a dispatcher for each 
menu. 


long mc; /* menu result */ 


short 
short 


menuld; 
menuitem; 


menuld = HiWord(mc); 
menuitem = LoWord(mc); 
switch Cmenuld) 
case Mdesk : break; 
/*apple menu not handling DA's */ 

dof ileCmenui tem); 

break; 
/* all disabled */ 

break; 
dofontCmenui tem); 


case Mfile : 
case Medit : 
case Mfont : 


reek; 

case Mstyl : dostyleCmenuitem); 
break; 

: dosizeCmenuitem); 


break; 


case Msize 


) 
HiliteMenuC0); 


/* dofont 


»* w »* www 


/ 


marks selected font and obtains 
font number. modifies size 

menu to reflect available sizes 
If item is zero, sets item to 3 
(geneva, the application default) 


dofontCitem) 


( 


short item; 


Str255 itemS; 
short cfont; 
short i; 

static short lastitem = @; 


/* actual font number */ 


if Citem equals 0) 
do 


( 

item++; 

GetI temCmenuFont, item, kitemS); 
GetFNum(&itemS, &cfont); 


while (cfont notequal 3); 
CheckI tem CmenuFont, lastitem, False); 
CheckI tem CmenuFont, item, True); 
lastitem = item; 
GetI temCmenuFont, item, ki temS); 
GetFNum(&itemS, &cfont); 
for Ci = 1; i € Nsize; i++) 
if (RealFontCcfont,sizes[i12) 
i SetI temStyleCmenuSize, i, OutlineStyle); 
else 
SetItemStyleCnenuS ize, i,8); 


ed. csetCedFont, cfont); 


S Ø, sets item to 3 (12pt) 


x 

* sets size menu, if item 
£3 

x 


dosize Citem) 
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) 


short item; 


static short  lestitem = Ø; 
if Citem equals 0) 

item = 3; 
CheckItem (menuSize, lastitem,False); 
CheckItem CmenuSize, item, True); 
lastitem = item; 
ed_cset(edSize, item); 


dostyleCitem) 


( 


short item; 


static short thestyle = @; 
short mitems; 

short i; 
short style; 
short styleflag; 
short of ff lag; 


if Citem equals 8) 

item = 1; 
style = item - 1; 
if ds 


/* move item to style range */ 
/* if not plain */ 


styleflag = 1; 

styleflag = styleflag << (style - 1); 

CheckI tem C(menuStyl, 1,False); /* unmark plain */ 
if i & styleflag) /* if style is marked */ 


/* un mark it */ 
CheckItem (menuStyl, item,False); 
rue = thestyle & ^stylef lag; 


else 


offflag = Ø; 
dii Citem) 


case iCon : 
CheckItemCmenuStyl, iExt, False); 
offflag = 64; 
break; 

case iExt : 
Check I temCmenuSty1, iCon, False); 
offflag = 32; 
break; 

cese iSuper : 
CheckI temCmenuSty1, iSub, False); 
offflag = 512; 
break; 

case iSub : 
Check I tem(menuSty1, iSuper, False); 
offflag = 256; 
break; 


CheckI tem CmenuSty1, item, True); 
thestyle &- “offflag; 
Mid “= stylef lag; 


else 


( 

thestyle = Ø; 

mitems = CountMI tems(menuSty1); 

for Ci = 2; i <= mitems; i++) 
CheckI tem CmenuStyl, i,False); 

CheckItem CmenuStyl, 1, True); 


ed. csetCedStyle, thestyle); 


/* dofile 
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x handles file menu 
*/ 
dof ileCitem) 
í short item; 
char *titlel; /* first title for window */ 
Rect boundsRect; 


E Citem) 


cese iNew : /* open the window */ 
titlel = "ABC Window"; 
Se tRect(&boundsRect, 58,58, 400, 200); 


theWindow = NewWindow(&windowRec, &boundsRect, 


CtoPstr( title1), True, documentProc, 


(WindowPtr) -1, True, Ø); 


DrawGrowIconCtheWindow); 
PtoCstr(title1); 
DisableItemCmenuF ile, 1); 
EnableI tem(menuF ile, 2); 
ed_new( theWindow); 
break; 


case iClose : /* close the window */ 
CloseWindowCtheWindow); 
theWindow = Nil; 
DisableItem(menuF ile, 2); 
EnableItemCmenuF ile, 1); 
break; 
cese iQuit : /* Quit */ 
ExitToShe11C); 
break; 


/* printwC) 
x 


* Displays strings and numbers in a 
* special window 


x 

* This function is designed to receive 

* 8e variable number of parameters. The 

* number is computed by the number of 

* percent signs in the contro] string. 

* If the number of parameters following the 
* control string does not match the 

* number of percent signs, expect 

* the unexpected. 

*/ 
printwCcs) 

char *cs; /* the control string */ 

"define Bufsz 14 /* size of buffer to hold */ 


/* converted numbers */ 


Static Rect — boundsRect; /* variables for */ 
static Rect windowRect; /* defining printw */ 
Static WindowRecord wrc;  , /* window, pw is */ 
static WindowPtr pw = QN& /* initialized to Ø */ 
static short linesz; * /* size of line */ 


WindowPtr oldport; /* save grafport here */ 
FontInfo info; 

short nl; 

Point pt; 

RgnHandle updrgn; /* needed for scrolling */ 
char numAsStr [Buf sz 1; /* number conversion */ 
short nsz; /* size of numbers (2 or 4) */ 
char **ts; /* ptr to ptr to ctrl string */ 
char X*ps; /* ptr to parameters */ 

ulong num; /* for number conversion */ 

short convchar; /* found conversion char */ 

short islong;  /* number is a long */ 
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char e /* char parameter */ 


char Xs; /* string pointer parameter */ 
long tcs; 
char *tps; 


/* Window rectancgle coordinates */ 


Rdefine wl ø 
#define wr 512 
#define wt 250 
define wb 342 
GetPort(&oldport?; 


/* save current graph port */ 
if Cpw equals 90) /* if window does not exist, */ 
/* open it */ 
SetRectC&boundsRect , w1,wt,wr , wb); 
pw = NewWindow(&wrc, &boundsRect, 
CtoPstrC""), True, plainDBox, 
CWindowPtr) -1, True, 9); 
GetFontInfoCkinfo); /* compute line height */ 
linesz = info.ascent + info.descent; 
nl = linesz; /* move down one line as */ 
) /* writing will be above */ 


else /* boundary. No need to */ 

nl = £; /* move line if already open */ 
SetPort(pw); /* Set graf port to this window */ 
Move(9,n1); /* Move (relative) */ 


ts = &cs; /* get address of control string ptr */ 
ps = (char *)ts;/* convert to pointer to params */ 

ps += sizeofClong); /* skip over control string ptr */ 
tcs = Clong)cs; 

tps = ps; 


while (¥cs) — /* loop until end of control string */ 


( 

i (*cs) /* check each character */ 

case '$' :  /* percent sign: check conversion */ 
cstt; /* point to next char */ 
convchar = False;  /* init for conv loop */ 
islong = False; 
do { /* loop til reach conversion char */ 

m (*cs) 


cese 'l' : /* indicates a long */ 
islong = True; 
cstt; 
break; 
case 'u' /* unsigned decimal */ 
cese 'd' : /* signed decimal */ 


if Te /* extrect numb */ 


num = *(ulong*)ps; 

nsz = sizeof (long); 
else 

num = *Cushort*)ps; 

nsz = sizeof (short); 


ps t= nsz; /* point to next */ 
ntoa(num,nsz, 'u' - 

/* convert & write number */ 
DrawStringCCtoPstr(numAsStr)); 
convcher = True; 
break; 

case 'S' : 
num = *(ulong*)ps; 
DrewStringC(CtoPstr(num?2; 
PtoCstr(num?; 
ps += sizeof(char*); 


*cs,numAsStr); 


convchar = True; 
break; 
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case 'C' : 
c = *Cushort*)ps; 
DrawChar(c); 
nsz = sizeofCshort); 
convchar = True; 
ps += NSZ; 
break; 
default /* all other char */ 
DrawChar(*cs); /* write char */ 
convchar = True; 


) while Cnot convchar); 


break; 
case '\n' : /* newline C'An' 2 control string */ 
GetPen(&pt); — /* find current pen position */ 


if Cpt.vtlinesz > wb-wt) 

/* if it goes off window, */ 
( /* scroll the window */ 
updrgn = NewRgn(); 
ScrollRect(&Cpw-?portRect2, 0,- 

linesz,updrgn); 

DisposeRgnCupdrgn?; /* no update */ 
Move(@,-linesz); /* move onto window */ 


Move(-pt.h, linesz); /* move beg of next line */ 
break; 

default : /* any other character just gets */ 
DrawChar(*cs); /* written on the window */ 


cstt: /* move pointer to next char */ 


) /* in control string end continue */ 
SetPortColdport); /* restore orignal graf port */ 
/* Convert numbers to ascii strings 

x Handles signed and unsigned 
x short and long values 
* Note: Length of string returned 
x must be large enough to 
x hold -2G (12 bytes) 
*/ 
ntoa(n, len, issigned,s) 
ulong n; * number to convert */ 
short len; /* size of n (2 or 4)*/ 
short issigned; /* signed flag */ 
í char Xs; /* string to return */ 
char ts[12];  /* temporary string */ 
int i = 8, /* counter, initialized */ 
ulong m; /* working copy of */ 
long Sn; /* to convert signed values */ 
if (n equals 0) /* if n is zero, place 'Ø' */ 
ts[it*12 '0'; /* in temporary string */ 
else 


/* if sign flag is set, */ 
/* convert to signed value */ 
if (len equals sizeofClong)) 
sm = Clong)n; 
else 
sm = (short)n; 
if Cissigned = sm < Ø) /* Check if value is */ 


if Jnd 


n = -sm, /* negative. If so, */ 
/* keep the flag end */ 
/* get the absolute value */ 
while (n) /* Convert number into escii */ 
( /* by repeatedly taking mod */ 


ts[(it*t12 n $ 10 + '0'; /* and dividing. This */ 
n /= 10; /* gives a string in */ 

/* reverse order */ 

/* If number was negative, */ 
/* stick a minus sign in */ 

/* the string. */ 
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if Cissigned) 
ts[it*] = '-'; 


= OO eee 


/* 
x 


s-'W'; 


do ( 


y = ts[--i]; 


while Ci); 


/* Reverse the string */ 


/* 


to the correct direction*/ 


/* Place null terminator on */ 


/* string */ 


* ed.c source 
x 


*/ 


*include "eabc.h" 
*Üinclude "ed.h" 


extern cher sizes[]; 


edrec edbuf ; 


/* 


* [nitialize some parts of the 


* edbuf structure. 


This coulb 


* easily be combined with ed new() 


*/ 

ra tO 
edbuf .cesc = 9; 
edbuf .cndx = 9; 
edbuf .supsub = £; 
edbuf .chars[@] = Ø; 
edbuf .linenum = Ø; 

) 

/* 


* save grafport, moves to 


x 
x 
x 


top of port, initializes 
font, style, and size. 
Initialize edbuf values so 
the calls to dofont will 
find different values than 
are being set. 


ed_newCaport) 


( 


/* 


GrefPtr aport; 
GrafPtr gp; 


edbuf .edport = aport; 
GetPort(&gp); 
SetPortCaport); 
MoveTo(0, 0); 

edbuf .faceledFont] = -1; 
edbuf .face[edStyle] = -1; 
edbuf .face[edSize] = -1; 
dofont(0); 

dostyleC0); 

dosize(C0); 

SetPort(gp); 


* Allows setting or getting 
* a value (size, font, style). 
* Is not used. 


*/ 
ed. setCnhat, value) 
short what; 
í short value; 


if (value >= Ø) 


edbuf .face[what] = value; 


returnCedbuf .face[what 1); 


© The Complete MacTutor, Vol. 2 


) 
/* 
* Called by any routine wishing 
* to change the size, style or font. 
* The change is indicated in the 
* cesc element of the edbuf structure, 
* and the value stored in the cface 


* element. The change is not applied 
* until a new character is written. 
x 


ed csetC(what, value) 
short what; 
short value; 


char wbit = 1; 


whit <<= what; 

if Cedbuf.face[what] equals value) 
edbuf .cesc &= "wbit; 

else 


edbuf .cesc |= wbit; 
ial = value; 


Writes the character c to the 
window. Before writing any 
character, it checks to see if 
Size/font/style have changed and 
effects the necessary changes. 


Since sub and super scripts and 
small caps styles are not supported 
by quick draw, they are handled 
here. 


Small Caps is implemented by using 
the font size one smaller on the 
menu for the lower case letters. 


Sub and superscripts are generated 
by shifting the position up or down 
one third of a line of the the current 


~ 
ZE HE »* »* »* x »* »* »* x x« »x« em ee e e 


size. 

ed. keyCc) 
char c; 
short *sp; 
FontInfo info; 
static short  linesz; 
GrafPtr 0p; 
Point pt; 
short lineinc; 
short linedec; 
GetPort(&gp); 


SetPortCedbuf .edport); 
lineinc = linedec = Ø; 
if ee 


if Cedbuf.faceledStyle] & Supbit + Subbit) 
linedec = -edbuf .supsub; 

edbuf .chars[edbuf .cndx++] = edbuf .cesc; 

sp = (short * )&edbuf .charsledbuf .cndx]; 

if ee & 1) /* Font */ 


*sp = edbuf .cfaceledFont]; 
edbuf .faceledFont] = *sp; 
TextFont(*sp); 

Sptt; 

edbuf .cndx +=2; 
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) 
if Cedbuf.cesc & 2) /ž Size */ 


*sp = Bou. M 
edbuf .faceledSize] = *sp; 
TextSizeC(sizes[*sp1); 
sptt; 

edbuf .cndx +=2; 


if i uzs & 4) /* Style */ 


*sp = edbuf .cfaceledStyle]; 
edbuf .face(edStyle] = *sp; 
TextFace((Style)*sp & Ox/7F); 
spt*; 

edbuf .cndx += 2; 


edbuf .charsledbuf .cndx**] = edbuf .cesc; 

edbuf .cesc = £; 

GetFontInfoC&info); 

linesz = info.ascent + info.descent; 

if Cedbuf .face[edStyle] & Subbit) 
edbuf .supsub = linesz / 3; 

else if Cedbuf .face[edStyle] & Supbit) 
edbuf .supsub = -linesz/3; 

else 
edbuf .supsub = 9; 

lineinc = edbuf .supsub; 


/*edbuf .charsledbuf .cndx**] = c;*/ 


if Cc equals ‘\r') 


GetPen(&pt); 
MoveC-pt.h,linesz * lineinc * linedec); 
edbuf . linenum++; 


else 


GetPen(&pt); 
Move (8, linedec + lineinc); 


/* ebc.h 

x 

* Local definitions to improve readability 
x 


*/ 


"define True 1 
#def ine False ø 
"define Nil Ü 
“define and && 
"define or | 
l 


define not 
"define equals = 
"define notequal ! 


/* unsigned longs and shorts 
* (unsigned longs may not be 
x available with all compilers 
s7 
"define ushort 
"define ulong 
"define uchar 


unsigned short 
unsigned long 
unsigned char 


/* General purpose external routines 
* String conversion routines 

* return a pointer to a char 

x 


extern char *CtoPstr(); 
extern char *PtoCstr(); 


/* 

*  ed.h 

x definitions for edit functions 
x/ 


"include "“quickdraw.h" 


"define — edFont Ü 
"define edSize 1 


def ine 


edStyle 


2 


if Cedbuf .faceledStyle] & Cepbit end islower(c)) 
"define Capbit 128 
TextSize(sizes[edbuf .faceledSize] - 112; "define  Supbit — 256 
DrawChar(toupper(c)); define Subbit — 512 
TextSize(sizesledbuf .faceledSize]]); 
) idu. edstruct 


else 
DrawChar(c); GrafPtr edport; 
Rect edrect; 
SetPort(gp); short face[3]; 
short cface(3]; 
short supsub; 
int toupper(c) short linenum; 
char c; char cesc; 
char chars[ 19081; 
return. (c)='a' aC c<='z') ? Cc-32) : c 5; short cndx; 
int islower(c) typedef struct edstruct edrec; 
char c; typedef edrec *edpointer; 


returnC Cc >= 'a') end (c <= 'z') ? True : False); 
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ABC's of C 
Drawing Shapes with Quickdraw 


One problem with writing software is that friends often 
want to know what it does. With most of these columns, 
frankly, there has not been much to show. This time, though, 
you can use the mouse to draw some simple shapes on the 
screen. Of course your friends will point out that MacDraw 
does everything we're going to do, and much better, too. But 
this one, we did ourselves, and that makes all the difference! 

QuickDraw Shapes and Operations 

QuickDraw can draw a number of shapes. This month 
we are going to cover only the simple shapes. (I define 
simple shapes as those that can be drawn directly without first 
defining what the shape is.) The simple shapes are: 


Rectangles 

Ovals (ellipses and circles) 
Round-cornered rectangles 
Arcs and wedges 


To this list we could also add lines. The functions to 
draw these shapes are built into the Mac's ROM. 

In drawing the shape, QuickDraw can do a number of 
different operations: 


Frame draws a hollow outline 

Paint fills the shape with the current grafPort's pen 
pattern and mode. 

Erase fills the shape with the background pattern 

Invert — inverts all pixels within the shape: black 


becomes white and white becomes black 
Fill fills the shapes with a specified pattern. 


In general, these operations work identically for all the 
Shapes. The shape is drawn, and the pen's location is not 
changed. Except for Fill, the operations require only the 
information needed to define the Shape. Fill also needs to 
know the pattern to use. Since we have no easy way to select 
a pattern (we haven't done custom menus yet, so we haven't 
made a pattern selection menu), this operation will not be 
used. 

The Toolbox supplies a separate function for each shape 
and operation. There are, for example, five functions to draw 
rectangles:FrameRect(), PaintRect(, EraseRect(), InvertRect(), 
and FillRect(). I wanted to select the shape and operation from 
menus and then draw with the mouse as with MacDraw. 

Alternative Designs 

One way to do this (assuming we had the menus built) 
would be to use a switch (case) statement based on the shape 
and operation: 

switch (shape) 
case rect: 
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€ File Edit Shape Operation 


Flg. 1 Our Drawing Program 


Switch Coperation) 
case Frame: 
case Paint: 
case Erase: 
case Invert: 
case Fill: 
case oval: 

switch Coperation) 


et cetera. 


This is a sort of brute force method. It would work, but 
it involves several pages of code to make a couple of simple 
selections. 

Another approach is to take advantage of C's ability to 
pass and use pointers to functions. To do this we obtain the 
addresses of the functions and arrange them in a double 
subscripted array. The problem of selection reduces to a 
problem of indexing into the array. 

Pointers to Functions 

Just as we can get the address of a variable and then 
assign a pointer to it, we can get the address of a function, 
assign a pointer to it and use the pointer to access the 
function. Kernighan and Ritchie discuss this on page 114. 

There are several step in using a pointer to a function. 
First, to get the address of a function, just use the name of the 
function without the parentheses. If fr rect() is a function, 
fr rect will be the address of the of the function. To use a 
function in this manner we must create a variable that is a 
pointer to a function. The following line does this: 

short (*drfunc)(); 

This rather strange looking line declares drfunc to bea 
pointer to a function that returns a short. Note that the 
parentheses around *afunc are required. Without them we 
would have: 

short *drfunc(); 
a function that returns a pointer to a short. I could not 
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use this declaration directly in the program but had to use a 
typedef: 
typedef short (*drfunc)(); 

Once this type is established, we can define some 
variables. In the program there is a variable, draw. 

drfunc draw; 

For the moment assume that draw points to a function (it 
has been assigned a value). To use draw we do the following: 

(*draw)(par1,par2); 

Again, the parentheses are needed to indicate that draw is 
a pointer to a function and we want to execute the function it 
points to. (Without the parentheses draw would be a function 
that returns a pointer). It is important to pass the proper 
number of variables. Since the call to the function is made 
through a pointer, compilers can do very little checking. 

The Drawing Functions 

I had originally hoped to avoid writing a bunch of 
drawing functions, but this plan changed. First, Lightspeed C 
does not allow us to take the address of Toolbox functions. 
They even have a special error message. This probably has to 
do with how they access the Toolbox and make the translation 
from C to Pascal calling conventions. This meant I would 
need at least a surround function for each Toolbox routine I 
wished to use. 

Secondly, I wanted to draw lines in the same way as the 
other shapes. Since the Toolbox does not handle lines as 
shapes, I would have to do it myself. This was complicated 
by the fact that the initial versions of these functions expected 
to receive rectangles. Rectangles are used to define all the 
Shapes. With lines, though, it meant taking apart the 
rectangle, figuring out which corner was the beginning, and 
keeping track of it. Needless to say, the line functions got 
very strange looking. To simplify the line functions, all the 
functions now receive two points. This had the side benefit of 
simplifying the oval functions, but it required that the 
surround routines create a rectangle before calling the Toolbox 
function. 

The other requirement for accessing the function via a 
pointer is that all the functions must receive the same number 
of parameters. In addition to a rectangle, the round rectangle 
functions get two parameters describing the oval width and 
height used in drawing the rounded corner. These are fixed at 
20. (Do try varying these. I was able to make some very ugly 
rounded rectangles). The arcs receive a start angle and the 
number of degress of angle to move (arcAngle in Toolbox 
terms). I fixed the arc angle at 90?. The start angle and the 
sign of the arc angle are adjusted as necessary to make the arc 
move correctly. These arcs were modeled after the ones in 
MacDraw. 

The result of all this is a single function, drdraw(), that 
draws all the simple shapes under mouse control! 

Speaking of the Mouse 

Another addition to the program this month is the code 
that changes the cursor. While it is not yet complete (it 
doesn't know about the window borders where the controls 
would go), it does change the cursor as the mouse moves 
around. AdjustCursor() receives a pointer to a window record 
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as a parameter and sets the cursor to the crosshairs (cursor 
number two) if the mouse is in the window and to the arrow if 
the mouse is not. The arrow cursor itself is not one of the 
four standard cursors but is defined in Quickdraw.h. 
AdjustCursor() is called once each time through the event 
loop. 

There are two other points that deserve some mention. 
One is that several sets of coordinates can be active at once. 
GetMouse(Q, for example, returns the mouse's position relative 
to the current or active window. The window's boundaries, 
however, are defined in terms of the screen or global 
coordinates. The functions  LocalToGlobal and 
GlobalToLocal() will switch a points coordinate system. 
Without the switch, the cursor changes magically out in the 
middle of the screen. 

Next Time 

We only did the simple shapes this time. I decided to 
wait on the others pending a discussion of the memory 
manager. Many of the functions we have used so far make use 
of the memory manager, and to do some things, we must be 
able to grab bits of memory. After that (I expect the program 
to be very brief - just long enough to demonstrate the 
operation) well return to Quickdraw and draw some more 
shapes. 

The Program 
" abc.h 
: Local definitions to improve readability 


x /* 


tdef ineTrue 
define False 
"idef ine Nil 
“define and 
#def ine or 

#def ine not 
#def ine equals 
#def ine notequal 


— tf —— #2 A @ — 
— go 


/* unsigned char, longs, shorts 
x Cunsigned longs may not be 


z available with all compilers 
*/ 
“define uchar unsigned char 


define 
def ine 


ushort 
ulong 


unsigned short 
unsigned long 


/* General purpose external routines */ 


externchar *CtoPstr();/* String conversion routines */ 
externcher — *PtoCstr(2;/* return a pointer to a cher */ 


I’ Quickdraw Drawing Program 

Shows off basic quickdraw shapes 
and operations. 

By Bob Gordon for MacTutor. 
Compiled with LightspeedC 


Important note for Mac C users: 
Every place you see event-)where, 
replace it with &event-> where 


w 9 w 0 »* »* »X* »* * 
~w 


“abc : h" 

"Quickdraw.h" 

"EventMgr .h" /* Events.h */ 
"WindowMgr.h" /* Window.h */ 
"MenuMgr .h" /* Menu.h */ 


®include 
#include 
include 
include 
ttinclude 
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/* defines for menu ID's */ 


define Mdesk 108 
#def ine Mfile 101 
"def ine Medit 102 
"def ine Mshape 183 
"define Mop 104 

/* File */ 

def ine iNew 1 
"define iClose 2 

“def ine iQuit 3 
/* Edit */ 

“def ine iUndo 1 
"def ine iCut 3 
"def ine iCopy 4 
#def ine iPeste 5 


/* Global veriebles */ 


MenuHendle ^ menuDesk;  /* menu handles x/ 
MenuHandle = menuF ile; 
MenuHandle ^ menuEdit; 
MenuHandle ^ menuShape; 
MenuHendle ^ menuOp; 
WindowPtr theW indow; 
WindowRecord windowRec; 
Rect dragbound; 
Rect limitRect; 
ra 


initsysO; /* system initialization x/ 
initepp(); /* application initialization x/ 
eventloop(); 


/* system initialization */ 
ce 


Init6raf(&thePort); 
InitFonts(); 

Ini tWindows(); 
InitCursor(); 

Ini tMenusC ); 
theWindow = Nil; /*indicates no window */ 
SetRect(&dregbound, 0,0, 512,250); 
SetRect(&1initRect,60, 40,508, 244); 


/* these two lines done */ 
/* automatically by Mac C */ 


) 


/* application initialization x/ 
(ipt) 


setupmenu(); 
drinitd); 


T ORN 


menuDesk = NewMenuCMdesk , CtoPstr("\24")); 
AddResMenu (menuDesk, 'DRVR'); 
InsertMenu (menuDesk, 8); 


menuFile = NewMenu(Mf ile, CtoPstrC"File")); 


AppendMenu CmenuF ile, CtoPstrC"New/N;Close;Quit/Q")); 
InsertMenu (menuFile, 0); 


menuEdit = NewMenu(Medit, CtoPstr("Edit")); 


AppendMenu CmenuEdit, CtoPstr("(Undo/Z; (-; CCut/X;( Copy/C; ¢ 


Paste/V;(Clear")); 
InsertMenu CmenuEdit, Ø); 


menuShape = NewMenu(Mshepe, CtoPstr("Shape")); 


AppendMenu CmenuShape, CtoPstr("Line;Rectangle; Oval ; Round 


Rectangle; Arc")); 
InsertMenu (menuShape, Ø); 
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menu0p = NewMenu(Mop, CtoPstrC"Operation"2); 


AppendMenu Cmenu0p, CtoPstrC"Frame;Paint; Erase; Invert; ")); 


InsertMenu CmenuOp, 0); 
DrewMenuBar(); 


) 


/* Event Loop */ 
Ton 


EventRecord theEvent ; 
char e 

short windowcode; 
WindowPtr WW; 


i A 
if REINO 


Enablel tem(menuF i1e,2); 
DisableItemCmenuF ile, 1); 
ia EDS INCOR): 


else 


EnableItemCmenuF ile, 1); 
DisableItemCmenuF ile,2); 


if (GetNextEventCeveryEvent, &theEvent)) 
B a 


case keyDown: 
c = theEvent.message & charCodeMask ; 
if CtheEvent.modifiers & cmdKey ) 
domenuCMenuKeyCc22; 
else if CtheWindow) 
break; 
case mouseDown: 
domousedown(& theEvent); 
break; 
default: 
break; 


) 

/* Arrow or Plus Cursor Shape */ 
AdjustCursor (Cu) 

WindowRecord  *w; 


Point pt; 
CursHandle curs; 
GetMouse(&pt); 
LocalToGlobal(&pt); 

if SERI is cel 


curs = (Cursor **)GetCursor(2); 
ye ms): 


else 


SetCursor(&arrow); 


) 


/* domousedown 
x handle mouse down events 
*/ 


domousedownCer ) 
EventRecord*er ; 
short windowcode ; 
WindowPtr whichWindow; 
short ingo; 
long size; 
long newsize; 
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RgnPtr rp; 
Rect box; 
Rect *boxp; 


windowcode = FindWindowCer-? where, 
&whichWindow); 
mee (windowcode) 


case inDesk: 
if CtheWindow notequal 0) 


HiliteWindowCtheWindow, False); 
penne eee 


break; 

case inMenuBar: 
domenuCMenuSelectCer-? where) ); 
break; 

case inSysWindow: 
SysBeep( 1); 
break; 

case inContent: 
if CwhichWindow equals theWindow) 


HiliteWindowCwhichWindow, True); 
DrewGrowIcon(whichWindow); 
drdrewCwhichWindow); 


break; 
case inDrag: 
DragW indowCwhichWindow, 
er-?where, &dragbound); 
DrewGrowIconCwhichWindow); 
breek; 
case inGrow: 
break; 
case inGoAway: 
ingo = TrackGoAwayCwhichWindow, er-> where); 
if Cingo) 


CloseWindow(whichWindow); 
ido = Nil; 


break; 


/* domenu 


handles menu activity 
simply a dispatcher for each 


menu. 

domenu(ac) 
long mc; /* menu result */ 
short menuld; 
short menuitem; 


menuld = HiWord(mc); 
menuitem = LoWord(mc); 
switch (menuld) 


case Mdesk : break, 
/* not handling DA's */ 
case Mfile : dofileCmenuitem); 


break; 
case Medit : /* all disabled */ 


break; 
case Mshape: doshape(menui tem); 
break; 
case Mop : dooper(menuitem); 
break; 
HiliteMenuC0); 
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doshapeC item) 
( short item; 


static short — lestitem; 


CheckItem CmenuShape, lastitem,False); 
CheckItem CmenuShape, iten, True); 
lestitem = item; 

) drshapeC item); 


dooper Ci ten) 


( short item; 
static short — lestitem; 


CheckItem Cmenu0p, lestitem,False); 
CheckItem (menuOp, item, True); 
if iT == 5) 


item = 8; 
SysBeep( 1); 


droperClastitem = item); 


dof ileCiten) 
short item; 


char *titlel; 
Rect boundsRect;. 


iir (item) 


case iNew : /* open the window */ 
title1 = "ABC Window"; 
SetRectC&boundsRect , 58,58, 400 , 200); 
theWindow = NewWindowC&windowRec, 

&boundsRect,CtoPstr(Ctitle1), True, documentProc, 
(WindowPtr?) -1, True, Ø); 

DrewGrowIconCtheWindow); 
PtoCstr(titlel); 
DisableI temCmenuF ile, 1); 
EnableItem(menuF ile,2); 
break; 

case iClose : /* close the window */ 
CloseWindowCtheWindow); 
theWindow = Nil; 
DisableI temCmenuF ile, 2); 
EnableI temCmenuF ile, 1); 
break; 

case iQuit : /* Quit */ 
ExitToShel1(); 
break; 


) 


/* 

* dr.c 

* drewing routines 

*/ 

include "ebc.h" 
include "“quickdraw.h" 
include “windowMgr .h" 


struct shapes 


short kind; 
Rect size; 
short oper; 


" 


struct shapes shepa[20]; 
short shapdx; 


fr. lineCstartpt, endpt) 
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/*title for window */ 


Point startpt,endpt; 


Movelo(startpt.h,startpt.v); 
LineToCendpt .h, endpt.v); 


fr-rect(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt, endpt, art); 
FrameRect(&rt); 


fr_oval(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(star tpt, endpt, &rt); 
FrameOval(&rt); 


) 

fr-rort(startpt,endpt) 
Point startpt,endpt; 

{ 


Rect rt; 
Pt2Rect(startpt,endpt,&rt); 
) FrameRoundRect(&rt,20,20); 


fr-arc(stertpt,endpt) 
í Point startpt,endpt; 


Rect rt; 

Rect trt; 

short sa; 

short aa; 

Pt2Rect(startpt, endpt, &rt); 
cp_arc(ért, &trt, &sa, kaa); 
FrameArc (&trt,sa,aa); 


cp-arcCirt,ort,startangle,arcangle) 
Rect — *i 


irt; 
Rect — *ort; 
short *startangle; 
short  *ercangle; 


short dh; 

short dv; 

static Point anchor; 

dh = irtoright - irt-»left; 
dv = irt->bottom - irt-) top; 
if vid (dh | dv) 


anchor .v = irt-> top; 
anchor .h = irt-> left; 


*ort = *irt; 


if Cirt- left equals anchor.h) 


if jas < anchor.v) 


ort- left -= dh; 
ort top -= dv; 
*startangle = 180; 
seal: = -99; 


-else 


ort left -= dh; 
ort- bottom += dv; 
*startangle = Ø; 
ye conte = 9g. 


else 
if idu: < enchor.v) 


ort-> top -= dv; 
ort->right += dh; 
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*startangle = 189; 
ele = 90; 
else 


ort right += dh; 
ort->bottom += dv; 
*startangle = Ø; 
*arcangle = - 99; 


er_line(startpt, endpt) 
í Point startpt,endpt; 


GrafPtr gp; 
Pattern tpat; 
GetPort(&gp); 
BlockMove(gp-?pnPat,&tpat,8); 
PenPat(gp->bkPat): 
MoveTo(startpt.h,startpt.v); 
LineToCendpt.h, endpt . v); 
PenPat(&tpat); 
er .rect(startpt,endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt, endpt, &rt); 
EraseRect(C&rt); 


er_oval(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt,endpt, art); 
EraseOval(art); 


er_rort(star tpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt, endpt, art); 
EraseRoundRect(&rt, 20, 20); 


er_arc(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 

Rect trt; 

short sa; 

short 4a; 
Pt2Rect(startpt,endpt, art); 
cp-arc(&rt,&trt,&sa, kaa); 
EraseArc (&trt,se,aa); 


pt_line(startpt, endpt) 
Point startpt,endpt; 


GrafPtr gp; 

Pattern tpat; 
MoveTo(startpt.h,startpt.v); 
LineToCendpt .h, endpt . v); 


pt_rect(star tpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt,endpt, &rt); 
PaintRectC&rt); 


pt_oval(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt,endpt, art); 
PaintOvalC&rt); 
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) 
pt_rort(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt,endpt,&rt); 
PaintRoundRect(&rt, 28,28); 


pt_arc(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 

Rect trt; 

short sa; 

short 88; 
Pt2Rect(startpt, endpt,&rt); 
cp-arc(&rt,&trt,&sa, aa); 
PaintArc C&trt,sa, aad; 


) 
in_lineCstartpt, endpt) 
Point startpt,endpt; 


GrafPtr gp; 

short tpnMode; 
GetPort(&gp); 

tpnMode = gp-?pnMode; 
PenModeCpatXor ); 
MoveToCstartpt.h,startpt . v2; 
LineToCendpt .h, endpt . v2; 
PenMode(tpnMode?; 


) 
in_rect(star tpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt, endpt,&rt); 
Inver tRect(&rt); 


in_oval(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt, endpt,&rt); 
Inver tOval C&rt); 


) 
in-rort(startpt,endpt? 
Point startpt,endpt; 


Rect rt; 
Pt2Rect(startpt,endpt,&rt); 
Inver tRoundRect(&rt, 20, 28); 


in-arc(star tpt, endpt) 
í Point startpt,endpt; 


Rect rt; 

Rect trt; 

short sa; 

short 86; 

Pt2Rect(startpt, endpt,&rt); 
cp-arcC&rt,&trt,&sa,&aa); 
InvertArc C&trt,sa,aa); 


) 

typedef short  C*drfunc2C); 

drfunc a[J[5] = (fr_line,fr_rect,fr_oval,frrort, fr_arc, 
pt_line,ptrect,pt_oval,pt_rort,pt_arc, 
er_line, er_rect,er_oval, er_rort,er-arc, 


in-line, inrect, in_oval, in rort,in. erc); 
CE 


short i 

for Ci = Ø; 
shaepa[ i**].kind 

shapdx = £; 


, 
i < 20; 
i 9); 


J 


drshape(code) 
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short code; 


shapa[shapdx].kind = code; 


droper (code) 


short code; 


shapa(shapdx].oper = code; 


drsize(r) 


Rect r; 


shapalshapdx].size = *r; 


drdraw(w) 


( 


WindowRecord — *w; 


Point startpt; 

Point thispt; 

Point endpt; 

Point lastpt; 

Rect thisrt; 

Rect lastrt; 

GrafPtr port; 

dr func frame; 

dr func draw; 

short angle; 

short dv, dh; 

Point Sp; 

Point ip; 

Point lp; 

short shapx; 

short operx; 

SetPort((GrafPtr dw); 

GetMouse(&star tpt); 

lastpt = startpt; 

PenMode(patXor ); 

PenPat(gray); 

shapx = shapalshapdx].kind - 1; 

operx = shapalshapdx].oper - 1; 

if (Cshapx < Ø) or Coperx < 0D) /* to prevent trying */ 
return; /* Xo use unselected items */ 

frame = a[Q][shapx]; /* get address of frame func */ 


via = aloperx][shapx];/* get addr of shape/oper func */ 
do 


GetMouseC&endpt?; 

thispt = endpt; 

LocalToGlobalC&endpt ); 

if (PtInRgnCendpt,w->»contRgn) and 
^ EqualPt(thispt, lastpt)) 


(*frame)(startpt, lastpt); 
(*frame)(startpt, thispt?; 
pou - thispt; 


) 
while CStillDownC2); 
(*frame)(startpt, thispt); 
PenMode(patCopy); 
PenPat(b lack); 
(*draw)(startpt, thispt); 


abs (num) 


short num; 


if (num « 8 ) 
return -num; 
return num; 


/* num < Ø ? return -num : return num ;*/ 


P4 


(t 
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Pascal Procedures 


Prototyping Desk Accessories 


This month I will try to provide an interesting 
explanation of how to program Desk Accessories. Rather than 
simply attempting to explain the purpose and function of each 
of the three main procedures used by DA's (which has, after 
all, been done), we will try an entirely different approach. We 
will start with a simple DA, and take for granted the fact that 
it works. We will then type this DA's code into MacPascal 
and attempt to get it to run. In the process we will learn a lot 
about DA's, and when it is all done we will have a useful tool 


for prototyping Desk Accessories. 


Perhaps at this point you are wondering "What do you 
mean, type it in and get it to run?" We can't make the system 
call a MacPascal procedure the same way it calls compiled 
68000 procedures, so we will write a program that attempts to 
duplicate the actions of the system and its relationship with 


DA's. [ A desk accessory simulator! -Ed.] 


To start with let's take a look at the DA we will be using 
as a subject. Its' code is listed below. Look at it briefly and 


then continue reading the text that follows. 
The Simple DA We Will Be Using 


procedure UpdateSelf (var device : deviceControlRec); 
begin 


with device do 
in 
SetPortCdct Window); 
BeginUpdateCdct Window); 


MoveToC 10, 38); 
DrawString('This is a test DA‘); 


EndUpdate(Cdct 1Window); 
end; ( of with ) 
end; ( of UpdateSelf ) 


procedure Open (var device : deviceControlRec; 
var block : ParamBlockRec); 
ver 
R : Rect; 
wP : windowPeek; 


n 
with device do 
begin 
setrect(R, 128, 128, 256, 256); 
dctlWindow := 


New indow(nil, R, ‘Test DA', true, 0, nil, true, 8); 


wP := pointerCordCdctlWindow2)2; 
wP* .windowKind := dctlRefNum; 
end; ( of with ) 
end; ( of open ) 


procedure Close (var device : deviceControlRec; 
var block : ParamBlockRec); 
begin 
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with device do 
begin 
DisposeW indowCdct Window); 
dctlWindow := nil; 
end; ( of with } 
end; { of close ) 


procedure Event (var device : deviceControlRec; 
var block : 
ParamBlockRec); 
var 
EventP : “EventRecord; 
begin 
( csParam holds a pointer to the event record ) 
copy it to EventP ) 
BlockMove(@block.csParam(@], @EventP, 4); 
with EventP^ do( eventRecord 
begin 
case what of 
1: ( mdown event ) 
SysBeep( 1); 
6: { update event } 
UpdateSelf (device); 
otherwise 
F ( ignore all other events ) 
end; ( case of what ) 
end; ( with ) 
end; ( procedure event ) 


procedure Ct! (var device : deviceControlRec; 
var block : PeramBlockRec); 
var 
poi : point; 
in 
setport(device.dctlWindow2; 
with block do 
begin 
case csCode of 
64 : ( accEvent ) 
Event(device, block); 


otherwise 
( " other codes CaccRun, accCursor, accMenu, 
accCut, etc.) } 
( are not used by this DA ) 


end; ( case of code ) 
. end;( of with block ) 
end; ( of Ctl ) 


The first thing to notice about this DA is that it does 
practically nothing. The Open procedure creates a window, the 
Ctl procedure only handles calls of type accEvent (which are 
passed to the procedure event). The only events handled are 
Update, which draws a string, and MouseDown which merely 
beeps. Finally, the Close procedure Disposes the window. 
That's all it does. The next thing to notice is that there are 
some data types referenced that MacPascal does not recognize. 
Scanning through the code we encounter a DeviceControlRec, 
and then the ParamBlockRec. Further examination reveals the 
type WindowPeek which is used once in the Open procedure. 
We will deal with these three types in a moment. The final 
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thing is the toolbox calls used by the DA. We will declare 
equivalent procedures to these and use "inline" to make the 
actual calls. It will be very straightforward with one minor 
twist. 


Now lets get back to the type declarations. 
DeviceControlRec is not found anywhere in Inside Macintosh! 
As it turns out, if you read the portion of the Desk Manager 
on “writing your own Desk Accessories" it will mention the 
three driver routines used and then refer you to the Device 
Manager for further details. In the Device Manager chapter 
they mention that all driver routines recieve a pointer to the 
calls parameter block in AO (there's the ParamBlockRec), and a 
pointer to the "Device Control Entry" in Al. On page 21, 
titled "A Device Control Entry" we find the description of 
what must be the DeviceControlRec. The description is not a 
Pascal type declaration but we can easily convert it into one. 
The only fields accessed by the simple DA are the 
dctlRefNum, and dctlWindow. DctlRefNum is the reference 
number of the driver (related to the number of the DA), and 
dctlWindow is a place to put a pointer to the window the DA 
uses. Once you become familiar with DA's the use of the 
other fields is easily found. 


The declaration of a ParamBlockRec is found in that same 
chapter. If we read the DA carefully we see that csCode and 
csParam are the only parts referenced, so we won't type all 
four of the variant parts, only what is needed. CsParam is 
declared as array[0..0] of Byte which seems real stupid and 
dangerous to me so I changed it to array[0..3] of Byte. In the 
DA csParam is used only as a pointer to an event record. It 
would be convenient to change the definition of csParam to 
^EventRecord, but lets stay with the standard form. IM 
assumes that all DA's (and all drivers) are written in assembly 
language. In assembly you can use csParam any way you 
wish. In Pascal the type checking gets in the way, so I have 
adopted the habit of useing BlockMove to copy things into an 
out of csParam. 


To find the definition of WindowPeek we look, naturally, 
in the Window Manager chapter of IM. To use this definition 
we must also provide declarations for a Handle, and for a 
StringHandle. As I mentioned in previous articles, MacPascal 
allocates 2 bytes for boolean types while Lisa Pascal allocates 
1 byte (1 is correct). We take this into account in the 
declaration. 


We are now ready to do the Type declarations, so here 
they are: 


Type Declarations for the Sample DA 


Lptr » ^longint; 

ptr = “integer; 

Handle = “ptr; 

Byte = 8..255; 

str255P = ^str255, 
stringHandle = “str255; 
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ParamBlockRec = record 


qLink : Ptr; 
qType : integer; 
ioTrep : integer; 


ioCmdAddr : ptr; 

ioCompletion : ptr; 

ioResult : integer; 

ioNamePtr : ^str255; 

ioVrefNum : integer; 

( Usually there are three variant parts here also. ) 
( DA's use only csCode and csParan. 

csCode : integer; 

csParam : arrey(0..3) of Byte; 


a 


PeremBlkPtr = *ParamBlockRec; 


WindowPtr = GrafPtr; 
WindowPeek = “WindowRecord; 


WindowRecord = record 
port : GrafPort; 
windowKind : Integer; 
visible : Boolean; 
(hilited : Boolean; } 
ee : Boolean; 
spereFlag : Boolean; ) 
StrucRgn : RgnHendle; 
contRgn : RgnHandle; 
updateRgn : RgnHandle; 
windowDefProc : Handle; 
deteHendle : Handle; 
titleHandle : StringHandle; 
titleWidth : Integer; 
ControlList : Handle; 
nextWindow : WindowPeek; 
windowPic : PicHendle; 
refCon : LongInt; 

end; 


DeviceControlRec = record 
dCitDriver : Handle; 
DcltFlegs : integer; 
dctlQueue : integer; 
DctlQHead : Lptr; 
DctlQteil : Lptr; 
DctlPosition : longint; 
DctlStorage : Handle; 
dCtiRefNum : integer; 
dCtiCurTicks : longint; 
dCtiWindow : GrafPtr; 
dCtiDelay : integer; 
dCtlEmask : integer; 
dCtlMenu : integer; 

end; 


Now let's attack the issue of the toolbox calls. We will 
make procedure declarations for the needed routines, and use 
inline in those declarations. This method is clearer than using 
inline directly in the code. In the main procedure we will use 
inline directly (for brevity). The NewWindow function is 
going to allocate a window record on the heap, and MacPascal 
reacts very poorly to this (you get an out of memory error). 
To alleviate this problem we pass a pointer to a window record 
to NewWindow. "We must remember later, when we are 
constructing the main procedure of our program, to declare a 
variable named GlobalWindow as a WindowRecord. The 
ToolBox interface is therefore: 
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ToolBox Interface routines 


(--- Toolbox routines used by DA ----------------------- ) 
( New indow used by Open. 

( Uses GlobalWindow variable for WindowRecord instead of ) 
( letting the system allocate the memory automatically. ) 


function New indow (wStorage : ptr; 


boundsRect : Rect; title : str255; 
visible : boolean; procID : integer; 
behind : windowPtr; 
goAwayF lag : boolean; 
refcon : longint) : WindowPtr; 


in 
NewWindow := pointer(LinlineFC$A913, @GlobalWindow, 
@boundsRect, @title, visible, 
procID, 
behind, goAwayFlag, refcon)); 
procede BeginUpdate CTheWindow : 
aiin, TheWindow); 
a dre EndUpdate CTheWindow : 
in 
inlinePC$A923, TheWindow); 


procedure DisposeWindow (TheWindow : 
in 


WindowPtr); 


WindowPtr); 


WindowPtr); 
inlinePC$A914, TheWindow); 


At this point all we have is enough declarations to 
survive a command-K check without getting a bug box. We 
still don't have the DA doing anything. The routines to 
operate the DA will all be contained in the main procedure, 
and all their variables will be declared as global. You will find 
the program at the end of this article. Now we will step-step 
through the system simulation that will run the sample DA. 


If you follow along in the code you'll see that the first 
command is to remove the menu hilite created by the Go 
command. We then set the dctlRefNum as if the system were 
opening the DA and that were its driver reference number. 
What the DA will do is set the WindowKind field of the DA's 
window to this number. Actually, if the WindowKind of any 
window is negative the Window Manager will not treat it 
normally. It therefore becomes necessary to cheat a little and 
use a positive number for dctlRefNum. Note that the same 
applies to the Menu Manager. Our sample DA does not use a 
menu, but if it did we would have to make that menu's id 
number positive or it would not be treated normally (Normally 
for an application menu that is. In a real DA we want the 
system to treat the menu differently.) 


We then call Open, passing along the two records. Block 
is still not set to any values, but Open does not look for any 
so it doesn't matter. Open sets dct!Window to the WindowPtr 
of the newly created window. Note that Open makes the new 
window in the back, and that immediately after the Open call 
the system calls SelectWindow and then ShowWindow. I 
know this is right because I have traced the code of the trap 
_OpenDeskAcc. 
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Now that the DA is Open, it can respond to Ctl (control) 
calls. When the system actually makes these calls they are of 
the form err:=PBControl(@Block,false), in other words, a 
normal device manager driver call. In a Pascal DA there is a 
header that converts the register based call into a procedure 
call. We will simply call Ctl directly. One type of control 
call that all DA's should respond to is those to cut and paste. 
Our sample DA doesn't, but we will include this in the 
simulation. To do this we will need a menu, like the Edit 
menu in an application, to generate the cut and paste 
commands. This is the purpose of the NewMenu call after 


Open. 


At this point we enter an event loop. The variable "quit" 
is set to false and we will loop until it is true. The first thing 
the larger event loop does is enter a smaller loop that waits for 
an event to occur. There are two types of control call that 
DA's can receive that are not connected with an event. These 
are to set the cursor and perform a periodic action. We will 
not concern ourselves with the timing of the periodic action, 
or when the DA should set the cursor. Instead we will just 
make Ctl calls of these two types until an event occurs. 
Seehow easy it is to make a Ctl call: simply set the csCode 
and call Ctl. 


Once an event occurs it is the system's job to decide if 
the event should go to a DA or somewhere else. We will go 
ahead and set up Block for an accEvent call and change it later 
if needed. In general a DA receives only update events unless 
it is the front window, in which case it gets almost all of the 
events. Rather than checking that now, we'll case out the 
event and check each event on an indivual basis to see which 
window should receive it. A good example is the first case, 
KeyDown. If the DA is in front then we make a Ctl call 
(already set up as type accEvent). Otherwise we do nothing, 
as the dormant MacPascal windows won't receive events. 


The next case is that of a MouseDown. For a mouse 
click we'll need another case statement to handle the various 
places the click could have landed. FindWindow will return a 
code that indicates where, and in which windoow, the click 
occured. No matter where the click was, if it was in a 
window, then that window should be in front. So, we call 
SelectWindow. The variable "fnd" is an integer that holds the 
code returned by FindWindow. We will handle the 
possibilities one at a time, and in numerical order. To 
understand the action of FindWindow better, consult the 
Window Manager chapter of Inside Mac. 


If the MouseDown was in the menu bar then we should 
call the Menu Manager function MenuSelect to find which 
menu item the user wants to choose. MenuSelect returns a 
Longint with different information in the upper and lower 
words. If the HiWord is equal to dctIMenu then the user has 
chosen the DA's menu; csCode is set to accMenu, and 
csParam is set to the MenuSelect result. Note that the 
application handles the menu events, not the DA. By the time 
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the DA finds out about it the menu has already been clicked, 
dragged, and released (MenuSelect does this). The DA uses the 
Longint MenuSelect result to determine what happened. If the 
HiWord from MenuSelect is not dctlMenu then it could be the 
Edit menu (a DA is not concerned with the others). I have 
arranged the menu put up earlier so that if we add 67 to the 
number of the menu item chosen it conveniently becomes the 
correct csCode for editing. We make a Ctl call accordingly. 


If the MouseDown was not in the menu bar, but was in a 
window, then several possibilities remain. If the click was in 
the content portion of the window then it is that window's 
responsibility to handle it. Normally these clicks are returned 
to the application. But, if the WindowKind is negative, then 
the Window Manager will assume that that window belongs to 
a DA and make a control call. We do similarly. I found out 
about this the hard way. If the DA forgets to set WindowKind 
in Open then the window shows up but is Strangely dead - this 
is most perplexing until you figure it out. 


If the click is in the drag bar of a DA window the system 
will drag the window. The DA never even knows what has 
happened. Also, if the click is in the close box then the 
system calls TrackGoAway and then Close. The DA finds out 
this has happened whne it gets a Close call, it must then close 
itself. In the simulation we set "quit" and then call Close after 
exiting the main event loop. 


We are done covering the MouseDown possibilities. All 
that remains are the rest of the event cases. For Update and 
Activate events a pointer to the window involved is in the 
message field of the event record. We check it, and make a Ctl 
call, if necessary. I am not sure how the system handles all 
the other event possibilities, so I pass them to the DA just in 
case. 


This covers all the functions of the DA Prototyping 
Program. I have used this program, or one of its cousins, to 
develop several different DA's, including the one presented in 
this column in November '85. I think that it is a very useful 
tool, and I hope you find it useful, too. 


DA Prototyping Program 


progrem Run. A. DA; 
uses 
quickdraw2; 


( Put type declarations here ) 


var ( Variables for main simulation of system. ) 
NOT for use by the DA ) 
device : DeviceControlRec; ( passed to DA ) 
block : PeremBlockRec; ( passed to DA ) 
SysEv : eventRecord; 
sysMenu : MenuHendle; 
poi : point; 
wPeek : WindowPeek; 
r : rect; 
fnd : integer; 
quit : boolean; 
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111 : longint; 
GlobalWindow : WindowRecord; 


( Put ToolBox interface routines here ) 


( Put sample DA code here } 


(Xxoooeeeeoeeoaaopoeneonaeeeeenonoooeoeoooooononoenoooaaa) 


(** Everything below this line is the simulation of the xxxx) 
(** system running the DA and should not be changed **) 
(eeopeeoeoeoenoocooanoonoooeneoeooeeoonoonooonoonooeooopeor) 
pegin ( of main simulation of system handling desk acc. } 
Desk Accessory simulation by Alan Wootton 11/11/85 } 


inlineP($A938, 8);{ HiliteMenu(0); remove Run hilite } 


device.dctlRefNum := -1 * (16 + 1); ( make this DA #16 } 

( Actually there is a problem with using negative numbers ) 

( like a real DA would, so we change it to a positive 
number. } 

device.dctlRefNum := -device.dctlRefNum; 

( If m DA has owned Resources it may have trouble finding 

them. 

Open(device, block); ( Open the DA ) 


inl inePC$A9 IF, device.dctlWindow); ( SelectWindow ) 
inlineP($4915, device.dctlWindow); ( ShowWindow ) 


( Meke a menu to simulate the applications Edit menu. ) 
sysMenu := Pointer(LinlineFC$A931, 13, 'sysEDIT')); 
(NewMenu( 13, 'sysEdit') 
inlineP($4933, sysMenu, 'undo'); (AppendMenu) 
inlinePC$A933, sysMenu, '??'); (AppendMenu) 
inlineP($A933, sysMenu, ‘cut'); (AppendMenu) 
inlinePC$A933, sysMenu, 'copy'); (AppendMenu) 
inlinePC$A933, sysMenu, 'paste'); (AppendMenu) 
inlineP($A933, sysMenu, 'clear'); (AppendMenu) 
inlinePC$A935, sysMenu, Ø); ( InsertMenu ) 
inlinePC$A937); (DrewMenuBar) 


quit := false; 


repeat ( until quit ) 
begin 


aret accRun and accCursor until an event occurs ) 
n 
( actually these shouldn't happen all the 
time like they do here ) 
block.cscode := 65; ( accRun ) 
Ctl(device, block); ( Device Manager Control call ) 
block.cscode := 66; ( accCursor 
Ctl(device, block); ( Device Manager Control call ) 


until getnextevent(-1, SysEv); 


( set up block to make a contro! call of type accEvent ) 
block.cscode := 64; 

111 := ordC@SysEv); 

BlockMoveC8111, eBlock.csParem[0], 4); 


case SysEv.what of 
po ( key, or key repeat event } 
if CLin] ineF($A924 =ord(device.dct1Window)) 
( if FrontWindow = device.dctlWindow then ) 
CtlCdevice, block); 
( if mousedown event ) 


[nd 


poi := SysEv.where; 
:* winlineF($A92C, poi 
( Findwindow poi, wPeek) $ 
if fnd Ø then ( if not on desktop ) 
n 
if fnd > 1 then 
inlinePC$A9 IF, wPeek); ( SelectWindow ) 
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@wPeek ); 


case fnd of 
l: ; ( mouse down is in MenuBer ) 
n 
111 := LinlineFC$A93D, poi); 
( 111:=MenuSelect(poi) j 
if hiwordC111) = device.dctlMenu then 
begin 
( if dctlMenu selected then make accMenu call ) 
block.csCode := 67; 
( 67 is accMenu ) 
BlockMove(@111, 
@Block.csPearam[9}, 4); 
CtlCdevice, block); 
end 


else 


begin 
if HiwordC111) = 13 then 
( Applications Edit menu? } 
begin 
( if mouse down in app.'s Edit) 
( then make accUndo. .accClear) 


( call ) 
Block.csCode := 
loword(111) + 67; 
CtlCdevice, block); 


end; 
inlineP($A938, 05; ( HiliteMenu( ) 


2 


end; 
3, 5 : ( if in content or grow part of 
window) 
if (wPeek^ .windowKind = 
device.dctlRefNum) then 
CtlCdevice, block); 
4 :( if in drag bar then drag window, } 
( no control call ) 


begin 
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setrect(r, -999, -999, 999, 999); 
inlinePC$A925, wPeek, poi, r); 
( DragWindow ) 
( if in GoAway box of DA window then make close call ) 


if winlineFC$A91E, wPeek, poi) > Ø 
( if TrackGoAway then ) 
dif (wPeek^ .windowKind = 
device.dctlRefNum) 


j 


i 


quit := true; 
( make close call later and end simulation ) 
otherwise 


end( case of fnd } 
end; ( of if fndd ) 
end;( cese mousedown ) 
6,8: ( if update, or activate event then make 
accEvent control call 
if sysev.message = ord(device.dctlWindow) then 
CtlCdevice, block); 
otherwise 
22 CtlCXdevice, block); ( send other events to acc 
end; ( of cese of event.what ) 
end( of repeat ) 
until quit; 


Close(device, block); 
( Application C or system ) calls CloseDeskAcc ) 


end.( of program, and of article, see ‘ya next month) 
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The Electrical Mac 


Direct Serial Port Access 


The serial ports continue to be a popular form of 
frustration for many of us. If you are tired of deciphering 
Inside Macintosh and would just like to talk directly to the 


Serial ports, stay tuned. 
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PORT PINOUTS 
SERIAL CONNECTORS 
Name Description 
CGND Chassis ground 
+5V 5 Volt output 
CGND Chassis ground 
TxD+ Transmit data - noninverted 
TxD- Transmit data - inverted 
+12V 12 Volt output 
HSK Handshake: CTS or TRxC 
depending on SCC mode 
RxD+ Receive data - noninverted 
RxD- Receive data - inverted 
MOUSE CONNECTOR 
Description 
CGND Chassis ground 
+5V 5 Volt output 
CGND Chassis ground 
X2 Horizontal movement line 
(connected to VIA PB4) 
X1 Horizontal movement line 
(connected to SCC DCDA) 
N/C Not connected 
SW Mouse button (connected 
to VIA PB3) 
Y2 Vertical movement line 
(connected to VIA PB5) 
Y1 Vertical movement line 
(connected to SCC DCDB) 
KEYBOARD CONNECTOR 
Name ipti 
CGND Chassis ground 
KBD1 Keyboard clock 
KBD2 Keyboard data 
+5V 5 Volt output 
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I'm going to describe some of the 
inner workings of the SCC and let you know where to write 
to get the technical manual, which will tell you the rest. I'm 
also including complete pinouts of all the Mac's connectors 
and a couple of cable pinouts. 
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Jeff Mitchell 

President 

Digital Solutions, Inc. 
MacTutor Contributing Editor 


EXTERNAL DRIVE CONNECTOR 
Name Description 
CGND Chassis ground 
CGND Chassis ground 
CGND Chassis ground 
CGND Chassis ground 
-12V Minus 12 Volt output 
+5V 5 Volt output 
+12V 12 Volt output 
+12V 12 Volt output 
N/C Not connected 
PWM Regulates the speed of the 

drive 
PHO Control line to send 
commands to the drive 
PH1 Control line to send 
commands to the drive 
PH2 Control line to send 
commands to the drive 
PH3 Control line to send 
commands to the drive 
WrReq Turns on the ability to 
write data to the drive 
HdSel Control line to send 
commands to the drive 
Enbl2 Enables the Rd line 
(otherwise Rd is 
high-impedence) 
Rd Data read from the drive 
Wr Data written to the drive 
CABLE PINOUTS 
IMAGEWRITER CABLE 

CGND 1 Chassis ground 

GND 7 Pins 3 & 8 connected 

on Mac side 

TxD-, RD 3 Receive data 

HSK, DTR 20 Printer ready line 

RxD+, GND Not connected 

on IW side 

RxD-, SD 2 Send data 
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RN IV 


1 CGND 1 Chassis ground 
2 CGND 3 Chassis ground 
3 CGND 5 Chassis ground 
4 CGND 7 Chassis ground 
6 +5V 11 

7 +12V 13 

8 +12V 15 

10 PWM 20 

11 PHO 2 

12 PH1 4 

13 PH2 6 

14 PH3 8 

15 WrReq 10 

16 HdSel 12 

17 Enbl2 14 

18 Rd 16 

19 Wr 18 


Direct serial communications 


The 28530 SCC is the chip which performs all of the 
Mac's serial communication functions, including the lowest 
level of the AppleTalk protocol. If you just want to hack out 
a quick program using the serial ports and don't want to bother 
with the serial driver, I'll show you how to disable interrupts 
(so the operating system doesn't interfere with you), set the 
transmission parameters, and send and receive data. 

The SCC is an extremely complex device, so if you want 
to do really serious programming, you need the technical 
manual. It is available from Zilog for $6.00 at the following 
address: 

Zilog, Inc. 

1315 Dell Ave. 
Campbell, CA 95008 
Attn: Publications 


Ask for the Z8030/Z8530 SCC _ Serial 
Communications Controller Technical Manual, part 
number 00-2057-02. 


In order to allow software written on the Mac to run on 
other machines, like the Lisa, hardware addresses should be 
referenced via a pointer located in low memory. For the SCC, 
there are two base address, one for read operations and one for 
write operations. 


SCCRd 
SCCWr 


EQU $1D8 
EQU $1DC 


SCC base read addr [pointer] 
SCC base write addr [pointer] 


Of course if we were concerned about portability we wouldn't 
write to the hardware directly anyway, so the absolute 
addresses are: 


sccRBase EQU $9FFFF8 
sccWBase EQU  $BFFFF9 


SCC base read address 
SCC base write address 


226 


There is a data register and a control register that can be 
accessed for each serial channel, A and B. A is the modem 
port and B is the printer port. The offsets from the base 
addresses for the control and data registers are: 


aData EQU 6 offset for A channel data 
aCtl EQU 2 offset for A channel control 
bData EQU 4 offset for B channel data 
bCtl EQU O offset for B channel control 


The registers are accessed by adding the offset to the 
appropriate base address, depending upon whether you want to 
read or write. 


There are some limitations to how you can access the 
SCC. First, there is an 8530 timing parameter which must 
be observed called the recovery time, which is the minimum 
time between SCC operations. This time is 2.2 microseconds 
which means if you have a polling loop you may have to pad 
it. 

The other limitations are specific to the Macintosh and 
are the result of the way the address decoding was 
implemented. Read operations must be byte reads of an even 
address and writes must be byte writes of an odd address. An 
odd byte read will reset the SCC and any word access will shift 
the phase of the Mac's high frequency timing. 


Z8530 TECHNICAL DESCRIPTION 


The operation of the SCC is controlled by 16 write-only 
registers and nine read-only registers. All registers are 8 bits 
wide, although some bits may not be used. Most of these 
registers are duplicated for each of the two channels, but some 
are shared by both. 

I'm only going to describe the registers that will allow 
you to change the transmission parameters and send and 
receive data. Some of the registers may have functions in 
addition to the ones I describe, so you'll need the manual if 
you want to explore all the SCC's capabilities. 

Write register 0 (abbreviated WRO) is the command 
register. There is a WRO for each channel. The primary 
function of the command register is to act as a pointer to all 
the other registers. 

To access any other register except the data registers, you 
first write the register number you want to access in the 
command register. The next read or write will be directed to 
that register. At the conclusion of this read or write cycle the 
pointer bits will be reset to zero, so the next write will be to 
WRO. The least significant 4 bits of the command register 
(D3 - DO) are used as the pointer bits. D7 - D4 must be zeros 
when writing to the pointer register. 

Transmit and receive interrupts are enabled in WR1. To 
disable interrupts, write a $01 to this register. This disables 
transmit and receive interrupts but leaves external/status 
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interrupts enabled. The external/status interrupt is used as a 
mouse input and if it is turned off, the mouse will freeze up. 

WR3 controls some of the receive parameters. D7 and D6 
set the number of bits per character. 00 = 8 bits, 01 = 7 bits, 
10 = 6 bits, and 00 = 5 bits. DO is the receiver enable. If DO 
is set to 1 the receiver is enabled while a 0 in DO disables it. 

WR4 contains control bits for both the receiver and the 
transmitter. D7 and D6 control the internal clock prescaler 
which divides the incoming 3.6864 MHz clock. These are set 
to 01 for a divide by 16 ratio. D3 and D2 set the number of 
stop bits. 11 = 2 stop bits, 10 = 1.5 stop bits, and 01 = 1 
stop bit. 00 is used when the chip is in synchronous mode. 
DO enables parity generation/checking if set, and D1 
determines whether parity will be even (D1 set) or odd (D1 
clear). D1 is ignored if parity is not enabled. 

WRS is the counterpart of WR3 for the transmit 
parameters. D6 and DS control the number of bits per 
character and operate identically to D7 and D6 of WR3 (i.e 00 
= 8 bits, . . ). D3 enables the transmitter if set. D1 enables 
the RTS output line on the chip, which is tied to the enable 
input of the RS-422 driver. D1 must be set for the driver to 
operate. 

WRS is the transmit buffer register. Once the transmitter 
is configured data can be output by writing to control register 
8, or by writing directly to the data register. Writing to the 
data register saves an extra write to the pointer register. 

WR39 is the master interrupt control register. There is 
only one WR9 which can be accessed from either the A or B 
channel. D7 and D6 select chip reset commands. Writing a 
11 will force a hardware reset of the chip. A 10 will reset 
channel A and a 01 will reset channel B. A 00 has no effect. 
D3 is the master interrupt enable bit. Clearing this bit will 
prevent the SCC from generating any interrupts. Once again, 
this will cause the mouse to freeze up . 

WR11 is the clock mode control register which selects 
the source of the transmit and receive clocks. To use the 
internal baud rate generator set D6 and D4 high and all other 
bits low. 

WR12 and WR13 are the time constants for the internal 
baud rate generator. The baud rate generator is a counter which 
is clocked by the input clock divided by the prescale value. In 
our case this is 3.6864 MHz divided by 16 (set in WR4) = 
230.4 KHz. 

Note that this is the AppleTalk data transfer rate. When 
used as an AppleTalk node the SCC operates in a synchronous 
mode and the baud rate generator is bypassed. 

The baud rate time constant is a 16 bit value, determined 
by the following formula: 


Time const. = (230400 / (2 * desired baud rate )) - 2 


For 300 baud, the time constant would be (230400 / 600) - 
2 = 382. This value must be split into upper and lower 8 bit 
values. The upper value goes in WR13 and is INT(382/256) = 
1. The lower value goes in WR12 and is 382 - (256 * WR13) 
= 126. As the baud rate goes up, the time constant becomes 
smaller. 
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WR14 contains some miscellaneous control bits. 
Setting this register to a $01 enables the baud rate generator. 

WRIS is the external/status interrupt control register. 
D3 must be set high to enable DCD interrupts which are used 
by the mouse. All other bits are set to zero. 


That takes care of all the write registers, leaving the read 
registers which are also accessed indirectly through WRO. 
Read register O (RRO) is the receive and transmit buffer status 
register. D2 is the transmit buffer empty bit. When set, the 
transmit buffer is empty and another character may be output. 
DO is the receive character available bit. When set it indicates 
that a character has been received and may be read from the 
receive buffer. 

RR8 is the receive data register. Received data may either 
be read here or through the data register directly, saving the 
write to the command register. 

RR12 and RR13 return the value of the baud rate time 
constant written to WR12 and WR13. 


USING THE SCC 


I haven't described all the functions of each register, and 
have even ignored some of the registers altogether. The 
technical manual is a must if you wish to use the chip's full 
capabilities. 

I've included a couple of programs for experimenting with 
the SCC. The first one, SCCHack, lets you fool around with 
the registers individually. The second one, HackTerm, is a 
terminal program which directly accesses the serial chip. Both 
are written in Modula-2, which may not be your particular 
language of choice, but it makes very readable code. 

Modula-2 was designed as a systems implementation 
language, which means that although it is a high level 
language, it has some low level constructs that can give the 
programmer direct access to the hardware. One of these 
constructs is the capability to anchor variables to absolute 
addresses, such as hardware locations. Modula Corp's 
implementation of Modula-2 limits these addresses to the 
lower 64K of the address space, however ($0000 - $FFFE). 
This particular implementation of Modula-2 also provides no 
direct mechanism for doing byte operations, which are required 
if we want to talk to the SCC. 

To circumvent these limitations I've declared a variable 
type SerPtr which is a pointer to a character array. SCCRd 
and SCCWr are declared to be of type SerPtr and anchored to 
the pointers located at $1D8 and $1DC. I then use SCCRd 
and SCCWr as pointers to index directly into the character 
array at the desired offset. Using a character array ensures that 
I do only byte accesses to the SCC. 


SCCHack begins with a read of the control register. This 
resets the pointer value to zero so we are in a known 
condition. It then enters a loop asking for the register number 
to access, and whether you want to read or write. If it is a 
read, it returns the value of specified read register in hex 
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format. If it is a write, it asks for the value to write in integer 
format (0 thru 255). It displays the hex equivalent and writes 
the value to the specified write register. Then it loops back to 
the beginning. Be prepared to reset your Mac to get back to 
normal after playing with this. 


HackTerm is a real simple terminal emulator that 
bypasses the serial driver. The first thing it does is reset the 
modem port and initialize the write registers. There are ten 
registers to initialize which are configured for a default 
condition of 300 baud, 8 data bits, 2 stop bits, and no parity. 
The order of initialization is important, as well as the values. 
The initial register values are: 


WR9 = $88. Reset channel A and enable all 
interrupts. 

WR1 = $01. Enable external/status (mouse 
input) interrupts. 

WR4 = $4C. Divide input clock by 16, 2 stop 
bits, no parity. 

WR11 = $50. Use baud rate generator output for 
transmit and receive clocks. 

WR12 = $7C. Lower byte of baud rate generator 
time constant. 

WR13 = $01. Upper byte of baud rate generator 
time constant. 

WR14 = $01. Enable baud rate generator. 

WR15 = $08. Enable DCD (mouse input) 
interrupts. 

WR3 = $C1. Receive parameters. 8 
bits/character, enable receiver. 

WHR5 = $6A. Transmit parameters. 8 


bits/character, enable transmitter, 
set RTS output high (enable 
RS-422 driver). 


After initialization, the program checks the keyboard for 
input. BusyRead returns either a character or a null if there 
has been nothing typed since the last call to BusyRead. A 
control C terminates the program and a control B causes a 
jump to the SetBaud procedure. SetBaud prompts you for a 
baud rate (300, 1200, . . ), computes the lower and upper 
bytes of the time constant and writes them to WR12 and 
WR13. 

If there is a keyboard input that is not a cntl-C, cntl-B, or 
a null, then PutChar is called which sends the character out the 
modem port. GetChar is called next which checks the input 
buffer and displays any received characters. 

You might want to call the serial driver routine SerReset 
after exiting this program to restore the chip to it's normal 
configuration and avoid any side effects later. 

Writing this article has convinced me that maybe the 
serial driver isn't so hard to use after all. But if you can't get 
the serial driver to do what you want, at least now you have an 
alternative. 


MODULE SCCHack; 


(* Written by Jeff Mitchell 
Digital Solutions, 1985 
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This program allows interactive manipulation 
of the internal SCC registers. It uses only 
channel A but I've included the offsets for 


channel B for reference. X) 
FROM Terminal IMPORT Read, Write, WriteLn, 
WriteString, ClearScreen; 
FROM InOut IMPORT  ReadInt, WriteHex; 
CONST 
(* Offsets into SCC registers *) 
aData = 6; (* A channel data *) 
act = 2 (* A channel control *) 
bData = 4; (* B channel data *) 
bCt1 = f (* B channel contro] *) 
cnt1.B = 2; (* ASCII value *) 
ent1-C = 3; (* ASCII value *) 
NULL = £9; (* ASCII value *) 
TYPE 
SerPtr = POINTER TO ARRAY [2..6) OF CHAR; 


(* Needed for byte access *) 


VAR 
SCCRd [1D8H]: SerPtr; 
SCCWr [ 1DCH]: SerPtr; 
ch: CHAR; 
reg: INTEGER; 


(* SCCHack *) 
ClearScreen; 
ch:= SCCRd*[aCt1); 


REPEAT 
WriteStringC'Which register ? '); 
ReadInt(reg); 
WriteLn; 
SCCWr*CaCt1):= CHRCreg); (* Set pointer *) 


REPEAT 
WriteStringC'Read or Write? '); 
Read(ch); 
WriteCch2; 
WriteLn 
UNTIL CCAPCch) = 'R') OR CCAPCchO = ‘W'); 


.(* Read pointer *) 
(* Write pointer *) 


BEGIN 


(* Ensure ptr reg = Ø *) 


IF CCAPCch) = 'R') THEN 
ch:= SCCRd^ [aCt1]; (* Read register *) 
WriteHexCCARDINALCch2,42; (* Display in hex *) 
WriteLn 
E 


WriteString( Register Value? '); 

ReadInt(reg); (* Integer value, not hex *) 

WriteLn; 

WriteStringC'Hex equivalent = '); 

Wr i teHex (CARDINAL (reg), 4); 

WriteLn; 

SCCWr^ [aCt11: CHRCreg) (* Write to register *) 
END; 


REPEAT 
WriteStringC'Try another? '); (* Fun, huh? *) 
Read(ch); 
WriteCch); 
WriteLn 

UNTIL CCAPCch) = 'Y') OR CCAPCChO = 'N'); 

WriteLn 

UNTIL CCAPCch) © 'Y') 


END SCCHack. 
MODULE HackTerm; 


(* Written by Jeff Mitchell 
Digital Solutions, 1985 


© The Complete MacTutor, Vol. 2 


This is a simple terminal emulator ch:= SCCRd*^ [aCt1]; (* Ensure ptr reg = @ *) 
which completely bypasses the operating 


system for serial I/0. x) (* Reset channel A, S VIS all interrupts *) 
FROM Terminal IMPORT BusyRead, Write, WriteLn, SCCWr^ [aCt1]:= CHRCO 
WriteString,ClearScreen; SCCWr^ [aCt1]:= GR CIT 
FROM InOut IMPORT — ReedInt; 
CONST (* Enable external status interrupts *) 
(* Offsets into SCC registers *) SCCWr^ [8Ct1]:2 CHRC1); 
(* A channel is the modem port *) SCCWr^ [aCt11:2 CHRC1); 
eDate = 6; (* A channel data *) 
act] = 2; (* A channel control *) (* Set Tx, Rx modes *) 
(* B channel is the printer port *) SCCWr^ [aCt1]:2 CHRC4); 
bData = 4; (* B channel data *) SCCWr^ [aCt1]:= CHRC762; 
bCt1 = Ø; (* B channel control *) 
cnt1.B = 2; (* ASCII value *) (* Set clock mode *) 
ecntl.C = 3; (* ASCII value *) SCCWr^ CaCt1]:= CHRC115; 
tus NULL = £; (* ASCII value *) SCCWr* LaCt1]:2 CHRC80); 
SerPtr = POINTER TO ARRAY [0..6] OF CHAR; (* Set default baud rate to 300 *) 
(* Needed for byte access *) (* Lower byte *) 
VAR SCCWr^ [aCt11:» CHRC 12); 
SCCRd [1D8H1: SerPtr; (* Read pointer *) SCCWr^ CaCt1):= CHRC 124); 
SCCWr (1DCH]: SerPtr; (* Write pointer *) 
ch,status: CHAR; (* Upper byte *) 
bRate: INTEGER; SCCWr^ [aCt1]:2 CHRC13); 
hiByte, loByte: CARDINAL; SCCWr^ [aCt1]:2 CHRC1); 
PROCEDURE GetChar CVAR ch: CHAR): BOOLEAN; 
(* Checks to see if a character has been (* Enable baud rate generator *) 
received and fetches it. *) SCCWr^ CaCt1):= CHRC14); 
SCCWr* [8Ct 11:2 CHRC1); 
BEGIN 
SCCWr*CaCt1]:= CHRC0); (* Tx, Rx status *) (* Enable DCD (mouse) interrupts *) 
status:= SCCRd" [eCt1]; SCCWr* faCt]]:= CHRC15); 
IF ODDCORD(status)) THEN (* Test bit Ø *) SCCWr^ (aCt1]:2 CHR(8): 
= SCCRd^ [aDatal; (* Rx char available *) (* Set Rx paremeters, enable receiver *) 
RETURN TRUE SCCWr^ [aCt11:» CHRC3); 
SCCWr^ CaCt1]:= CHRC 193); 
RETURN FALSE (* No char received *) (* Set Tx parameters, enable transmitter *) 
END SCCWr*LaCt1]:= CHRC5); 
END GetCher ; SCCWr^ [aCt1]:2 CHRC 106); 
PROCEDURE PutChar CVAR ch: CHAR); BusuR , 
(* Waits until transmit buffer empty then ig cad ee 
outputs a character. REPEAT 
IF ORDCch) = cnt1.B THEN 
BEGIN Se tBaud 
REPEAT (* Wait until xmit buffer empty *) ELSE 
SCCWr*CaCt1]:= CHR(Ø); — (* Tx, Rx status *) IF ORDCch) €» NULL THEN 
status:= SCCRd" [eCt1] PutChar(ch) 
UNTIL ODDCORD(status) DIV 4); (* Test bit 2 *) END 
SCCWr* [eDeta]:» ch (* transmit char *) END; 
END PutCher; WHILE GetChar(ch) DO 
| WriteCch) 
PROCEDURE SetBaud; 
(* Compute the time constant for the baud BusyRead(ch); 
rate generator and split it into high UNTIL ORD(ch) = cnt1.C 
and low bytes. *) END 
BEGIN END HackTerm. 
WriteLn; 
WriteString( Desired baud rate? '); 
ReadIntCbRate); 
WriteLn; 


(* Compute baud rate generator time constants *) 

hiByte:= CTRUNCC115000.0 / 
FLOATCCARDINALCbRate2)) - 2) DIV 256; 

loByte:= CTRUNCC115000.0 / 
FLOATCCARDINALCbRate))) - 2) MOD 256; 

SCCWr* [aCt1]:2 CHRC 13); 

SCCWr^ CaCt1]:= CHRChiByte); 

SCCWr*CaCt1]:= CHRC12); 

SCCWr* [aCt1]:» CHRCloByte) 

END SetBaud; 


BEGIN (* HackTerm *) 
ClearScreen; 
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Pascal Procedures 
Mac Sound Made Simple 


This month we will attempt to coax some sounds from 
the Mac. We will try all three of the sound producing modes 
on the Mac. And, since there is a problem, I will present 
what I think is a better Pascal interface to the Sound Driver. 
Finally, I will introduce a method of saving sound effects in a 
standard form for later use. 


The Sound Driver 


The first source of information should be the Sound 
Driver chapter of Inside Macintosh. The first apparent fact 
about the Sound Driver is that it supports three different forms 
of synthesis. All three modes are reached by calling 
PROCEDURE StartSound( synthRec : Ptr ; NumBytes : 
LONGINT ; completionRtn : ProcPtr ) with synthRec set 
to the proper values. Since StartSound is defined in all three 
Pascals we are likely to use (Lisa Pascal, TML Pascal, and 
MacPascal; On-Stage Pascal was not available at the time of 
this writing), we will work in MacPascal and assume that our 
work is easily transportable to the others. As a driver, the 
Sound Driver will accept standard Device Manager control 
calls. There are predefined routines that make the driver calls 
for us in most cases. The Sound Driver is in the ROM and 
never needs an Open call (or a Close). As drivers go, it is 
fairly simple to deal with, so we won't go into extreme detail. 
Advanced users will want to use completion routines and other 
driver features. 


Before we start making our first sound, it will be 
worthwhile to acknowledge how it is that the Mac can make 
sound at all. There is a special area in RAM where sound 
information is stored (much as there is a designated area of 
RAM that holds the screen information). Every time the 
video circuitry has completed painting one line on the screen, 
a byte is fetched from the sound RAM, and sent to a digital-to- 
analog converter. From there, the analog signal is sent to the 
speaker. A sound byte is processed 370 times for each 1/60th 
of a second. There are 60 'ticks', and also 60 frames of Mac 
video every second. This means that every second, 
60*370=22,200 bytes, are processed by the sound circuitry. 
The Sound Bytes are meant to represent an output voltage at 
the speaker, with 255 being greatest and 0 being smallest (we 
will use 128 for a neutral point). So you see, the Mac is not 
much of a synthesizer at all. All it really can do is play back 
data. Any other functions desired will have to be provided for 
in software. Every tick the same 370 bytes in memory are 
used, so unless we want to hear the same thing over and over, 
60 times per second, we will have to replace all 370 bytes 
repeatedly. If we had to do this ourselves we'd be talking 
assembly language now. Fortunately, the Sound Driver is in 
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assembly language and it will do this for us. And it will do it 
three different ways. 


Our main goal is to simply get program shells of the 
three sound modes in action, and to defer until later those data 
structures and routines one may use in a complex application. 


The Square Wave mode 


The square wave mode of synthesis appears to be the 
simplest. All the Sound Driver has to do, 60 times per 
second, is fill the sound buffer (370 bytes) with alternating 
values. If every other byte were 0 and 255, then we would get 
the loudest sound and the highest note (370/2 alternations per 
tick* 60 ticks per sec = 11,100 Hz). If one tick the 370 bytes 
were all 128, and the next tick they were all 129, we would 
get a very quiet note at 30 Hz. (You probably couldn't hear it 
from the Mac speaker). I don't think this is actually how the 
Sound Driver does it, but you get the idea. 


Here is a MacPascal program that should get some 
different tones using the Square Wave Mode. 


program Square_Wave_Scale; 
const 


notecount = 31; 


var 

i : integer; 

MySWSynthRec : record 
mode : integer; 


tones : arreg[ 1. .notecount] of record 
count, amplitude, duration : integer; 
end; ( of tones } 
end; ( of nySWSynthRec ) 


in 
with MySWSynthRec do 
begin 


mode := SWMode; 

for i := 1 to notecount do 
with tones(i)] do 

begin 


count := i * 64 + 256; 
amplitude := 255 - i * 8; 
duration := 30;( 1/2 sec. } 
end; 
Star tSound(@MySwSynthRec, sizeof (MySWSynthRec), nil); 
ShowText; 
Writeln('press mouse to stop'); 
repeat 
until button; 


S topSound : 


The problem is that Square Wave. scale does not work. 
The SWSynthRec is filled out correctly; the mode is set, and 
the tones are filled in. All is well, but there seems to be 
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something wrong with StartSound. The likely culprit is the 
CompletionPtr parameter. According to the MacPascal 
manual, you pass the address of a procedure if you want that 
procedure to be executed when the sound is done. MacPascal 
will (currently) not allow you to get the address of any of its 
procedures. If you want the sound to start, and then finish 
before the program resumes, you are to use pointer(-1). When 
I did that the Mac locked up, and I had to reboot. If you want 
the sound to start, and then for the program to resume before 
the sound is done (seems like a good idea), use nil. When I 
did that nothing happened. Perhaps we should junk 
StartSound. 


This brings up an interesting point. Clearly the point of 
this completion routine business is to be able to splice two 
sounds front to back with no seam. If our program has to 
wait for the first sound to finish, then there will be a delay 
(especially in MacPascal) before the next sound can be started. 
StartSound is going to have to make a Device Manager call 
(in this case PBWrite) to start the sound. To do that it will 
need to use a Parameter Block Record. What happens to that 
record when a second sound is started if the first is not done? 


What must be done is to create our own version of 
StartSound. We will use two parameter block records. That 
way one can be filled out and then passed to the device 
managers I/O queue while the other is busy. Our sounds will 
follow one another naturally without much fuss or muss. The 
predefined procedure ‘Generic’ will be used to make a Device 
Manager call. Let's cover this strategy in more detail. 


First, declare the procedure. We will call it myStartSound, 
and use the same parameter list, even though completionRtn 
will not be used. 


Second, the Parameter Block Record. Instead of using the 
entire record declaration, found in the Device Manager chapter 
of Inside Macintosh, we will use an array of integers and use 
BlockMove to move data into the record. Note that the 
numbers used alongside the Device Manager routine 
descriptions must be divided by two to get an index into the 
array of words. Only ioRefNum, ioBuffer, and ioReqCount 
are used, so this is reasonable. You must declare the 
parameter blocks at the outermost level possible, ie. they 
must not go away because the procedure they are defined in is 
done. Also, note that MacPascal erases them to zero for us. 
In another Pascal you should do that during initialization. 


Third, find a method of choosing which parameter block to 
use. The boolean variable AUsed is used to indicate which 
Parameter block was used last. It is toggled with every call. 
Once we know which block we are using, its ioResult field is 
checked to make sure it is done before modifying it. 


Finally, we need a method of making a Device Manager 


Write call. The Sound Manager chapter tells us to set 
ioRefNum to -4, to set ioBuffer to point to the SynthRec, and 
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to set ioReqCount to NumBytes. To make the call we declare 
an array of 13 longints which Generic will use to set the 
68000 registers (AO to A4 then DO to D7. See Advanced 
Mac'ing, MacTutor, Vol.1 No. 5 for the introduction of 
Generic) for the toolbox call. The first longint in the array is 
AO and that is set to the address of the Parameter Block. The 
number of the PBWrite toolbox routine is $A003, and we add 
$400 to it which causes asyncronous operation. $5 


If you add the following to Square Wave, Scale then it will 
work properly. 
( These two types are needed by MyStartSound ) 


Ptr = “integer; 
PeremBlockFeke = array(0..30] of integer; 


put pee variables in with the rest of the global ver's ) 
var 
blockA, blockB : ParamBlockFake; ( for myStartSound ) 
AUsed : boolean;( for MyStartSound ) 


( use this procedure everywhere you might ) 
( otherwise use MySound ) 


procedure MyStartSound (SynthRec : ptr;numbytes : longint; 
CompletionRtn : Ptr); 
( CompletionRtn ignored j 
var 
regs : array(2..12] of longint; ( for generic ) 
BlockPtr : ^ParemBlockFake; 
in 
1f Aused then 
BlockPtr := @BlockA 
else 
BlockPtr := @BlockB; 


Aused := not Aused; 
while BlockPtr*[8] © Ø do ( wait for ioResult to clear) 


BlockPtr^[12] := -4;( set ioRefNum ) 
BlockMoveCéSynthRec, 8BlockPtr^[16], 4); ( ioBuffer } 
BlockMoveCénumbytes, 8BlockPtr^[18], 4); (ioReqCount) 


( The following two lines do PBWrite(BlockPtr, true) ) 
regs(0] := ord(BlockPtr2; ( set AØ for Generic ) 
Generic($A403, regs); ( Write,async ) 
end; 


Please note that all the previous technical talk you just 
encountered is for the sole purpose of creating a new version 
of StartSound. If you didn't understand it, don't worry. Just 
use myStartSound everywhere you would use StartSound, and 
set completionRtn to nil. What we have actually done is to 
simplify the situation, with the small cost of having to paste 
myStartSound into your sound programs. 


The Four Tone mode 


The Four Tone mode is a little more complicated. It 
provides a more complex synthesis function as well. The idea 
is that you provide a waveform table of bytes for each of four 
sounds. The Sound Driver will move through the tables, at a 
rate you specify, sum the four values for each byte, and place 
the result in the 370 byte sound buffer. Since it must sum 
370*4 bytes 60 times per second, in addition to calculatin 
which byte from which table to use, this takes about 1/120 
of a second. When the Mac is making four tone sounds it 
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appears to run at half speed. 


The waveform tables are 256 bytes long. You may put 
into them any numbers you wish, thereby producing different 
sounds. We will talk more about waveforms later. The 
Sound Driver does not simply put the first byte in a wave 
table into the first byte of the sound buffer, and the second in 
the second, etc. What it seems to do is add the fixed (fixed 
numbers have an integer in the upper half, and the lower half 
is a fraction) quantity Rate to the (fixed?) quantity Phase, and 
then to take the result mod 256 as the index into the wave 
table. This means that a Rate of 2 will use every other byte 
in the wave table and a Rate of 1/2 will use every byte twice. 


From a programming point of view all you have to do is 
fill out the data structures and call StartSound. The 
application point of view is left up to you. Let me now 
present a program that will make a single, pure tone using the 
Four Tone mode. 


Program Four_Tone_Test; 
uses | 


Sane; 

type( for MyStartSound ) 

Ptr = “integer; 

PeremBlockFeke = array[0..30) of integer; 
var 

ratel : integer; 

MyFTSynth : FTSynthRec; 

myFTSound : FTSoundRec; 

SinWeve : packed array(?..255) of cher; 


blockA, blockB : ParemBlockFeke; ( for myStartSound ) 
AUsed : boolean; ( for MyStertSound ) 


( Paste myStartSound here ) 


( Fill the array SinWave with bytes (chars) ) 

( representing one cycle of a sine wave ) 

( note that numbers are from Ø to 255 so that ) 
( 128 is 'zero' ) 


FillSinWeve; 
var 
i : integer; 
f, pi : extended; 
begin 


pi :* ercTenC1) * 4; 
f := 2 * pi / 256; 
for i := Ø to 255 do 
SinWave[i] := chr(Num2Integer(sin(i * f) * 120 + 128»); 


/ 


begin ( of main ) 
FillSinWave; 
ShowText; 


MyFTSynth.mode := FTMode; 

MyFTSynth.SndRec := @MyFTSound; 

( Note that all MacPascal Records are initialised ) 

( by the system to zero. In another Pascal you may ) 
( have to remember to initialize everything j 

( ie. when we start all rates ere Ø 


with MyFTSound do 

begin 
Duration := 1000; 
SoundiWave := @SinWave[@]; 


MyStar tSound(@MyFTSynth, Sizeof(MyFTSynth), nil); 
ratel := 1024; 
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t 
Duration := 1000; 
Sound IRate := FixRatioCratel, 256); 
ratel := ratel + ratel div 16; 
writelnC'The rate is', ratel, ' div 256, = ', 
FixRatioCrate!, 256)); 
if ratel >= 2048 then 


ratel := 1024; 
until Button; 


StopSound; 
end. 


The Sane function Sin which you might normally think of 
as being used to find the vertical component of an angle (the 
angle is in radians, ie. 2*pi=360°, where pi is the ratio of the 
diameter to the circumference of a circle) is also used to 
produce the numbers required for a pure musical tone. Certain 
California Types might wax philosophical about this duality 
of function in nature, but we won't do that here (do California 
Types eat quiche?, do Real Programmers wax philosophical?). 
If you divide 2*pi by 256 and then multiply by a loop index 
that goes from 0 to 255, then you will get numbers 
corresponding to one complete waveform. This is what it 
looks like graphically. 


Fig. 1 Sound Representation 


Note that when you are using Four Tone mode, you don't 
have to call StartSound over and over if you don't want. If 
you keep the duration large then you can simply change the 
values for each of the four tones 'on the fly. Remember, that 
while the sound is still going, the data structures belong to the 
Sound Driver. You may modify them, but do not delete them 
(like if they were declared inside a procedure that ended, or if 
you allocated them on the heap and then later disposed of 
them). When you are done, call StopSound, and all records 
being used are released. 


Now that we have the Four Tone synthesizer working, try 
this program for a more interesting result. Sorry, but unlike 
graphic programs, there is no easy way to publish what the 
output of these programs is like. You have to type them in 
and see (I mean hear) for yourself. 


program Four. pert. sound; 


Uses 
sene; 
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const 
BaseNote = 1024; 


type 

Ptr = “integer; 

ParamBlockFake = array[9..30] of integer; 
var 

ratel, rate2, rate3, rate4 : integer; 
MyFTSynth : FTSynthRec; 

myFTSound : FTSoundRec; 

SinWeve : packed array[%..255] of char; 


blockA, blockB : ParamBlockFake; ( for myStartSound ) 
AUsed : boolean; ( for MyStartSound ) 


( Paste myStartSound here } 
{ Paste FlliSinWave here } 


in 
FillSinWave; 
ShowText; 


MyFTSynth.mode := FTMode; 
MyFTSynth.SndRec := @MyFTSound; 


with MyFTSound do 
in 
Duration := 1000; ( will be made infinite later ) 


Sound iWave := @SinWave[@); 


Sound2Wave := @SinWave([O]; 

Sound3Wave := 8SinWave(0]; 

Sound4Wave := eSinWavet£1; 

MyStar tSound(@MyFTSynth, Sizeof(MyFTSynth), nil); 
Rate! := BaseNote; 

Rate2 := BaseNote; 

Rate3 := BaseNote; 

Rate4 := BaseNote; 

repeat 

begin 


Duration := 1000; ( keep going forever ) 
Ratel := Ratel + Rate! div 8; 

Sound iRate := FixRatioCRatel1, 256); 

if Ratel > 2 * BaseNote then 


Ratei := BeseNote; 
Rate2 := Rate2 + Rate2 div 8; 
Sound2Rate := FixRatioCRate2, 256); 
if Rate2 > 2 * BaseNote then 
begin 
Rate2 := BaseNote; 
Rate3 := Rate3 + Rate3 div 8; 
Sound3Rate := FixRatioCRate3, 256); 
if Rate3 > 2 * BaseNote then 
begin 
Rate3 := BaseNote; 
Rate4 := Rate4 + Rate4 div 8; 


Sound4Rate := FixRatioCRate4, 256); 


if Rate4 > 2 * BaseNote then 
Rate4 := BaseNote; 
end; { rate3 } 
end; ( rate2 } 
end; ( rate 1) 


until button; 


end; ( with MyFTSound ) 
StopSound; 
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You may find it interesting to experment with different 
waveforms in this program. Those musical types among us 
will probably be able to modify the numbers and get a proper 
musical scale. 


The Free Form mode 


With the Free Form synthesizer you are able to play a - 
digitized sound of almost any length and composition. The | 
data used is simply an array with the sound bytes in it. 
Astonishingly realistic sounds can be produced. Some popular 
games for the Mac use this mode to create sound effects that- 
are derived from recordings of real sounds. 


In the examples I present we will calculate the data to 
produce and entire second of sound, ie. 22,200 bytes. Since it 
can take some time to calculate so many bytes, we will break 
the task into two parts. One program will calculate the bytes, 
and another will be used to play them. Once you have spent a 
long time producing a complicated sound effect it would be 
nice to have a place to put it until you want it again. The 
natural place would be the Scrapbook. In order to get to the 
Scrapbook it is necessary to first make it to the clipboard. In 
the Oct. 85 (Vol.1, No.11) issue of MacTutor I presented a 
routine to save Quickdraw pictures of type 'PICT' on the 
clipboard. The name of this was 'Pict to Clip. Allow me to 
present Wave to Clip. You will find it embedded in the 
following program that calculates one second of a pure tone. 


program FFSine Weve to. Clip; 
uses 
Sene; 
const 
WTSize = 22200; ( 370*60-0ne second of sound ) 


ptr = “integer; 
Handle = “ptr; 


MySynthH = “MySynthP; 
MySynthP = “MySynthRec; 


mySynthRec = record 
mode : integer; 
rate : fixed; 
WaveBytes : packed array[@..22199] of char; 


4 


ver 

waveH : MySynthH; 

i, n, ticks, samples : integer; 
pi, Freq : extended; 


procedure Weve to Clip (waveH : MySynthH; 
name : str255); 
ver 
TheType, llength, 111 : longint; 
str : str255; 
( The Hlock that is predefined does not work!!! ) 


procedure Hlock (H : Handle); 
var 
regs : erre&y(2..12) of longint; 
in 
regs[0] := ord(h);( set Ad ) 
Gener ic($A829, regs); 


end; ( of Hlock ) 
begin( of Wave_to_clip ) 
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111 := LinlineFC$A9FC); ( ZeroScrep ) 

str := '"WAVE'; 

BlockMoveCéstr[1], @TheType, 4);( TheType:='WAVE' ) 
llength := GetHandleSize(waveH); 
HlockCpointerCord(waveH22); 

111 := LinlineFC$A9FE, llength, theType, waveH^); 

( PutScrep) 

Hunlock(pointerCordCwaveH22); 


llength := Length(name); 

str := 'TEXT'; 

BlockMoveCéstr[11], @TheType, 4);{ TheType:='TEXT' ) 
111 := LinlineFC$A9FE, llength, theType, @name[1]); 
( PutScrap} 


s 


begin 
waveH := NewHandle(WTSize + 6); 
waveH**.mode := FFMode; 
waveH^^.rate := FixRatioC1, 1); 


pi := arcTan(1) * 4; 
Freq := 2 * pi / 22200 * 1924; (1024 Hz ) 


ShowDraw ing; 
textmode(srcCopy); 


1 := 8; 
for ticks := 1 to 60 do 
begin 
movetoC1, 256 - n); 
for samples := 1 to 370 do 
begin 
n :* num2integer(sinCi * Freq) * 64 + 128); 
waveH^^ .WaveBytesli] := chr(n); 
linetoCsamples, 256 - n); 
i:s i+ Í; 


end; 
DrawString(StringofCticks)); 


end; 
Wave_to_ClipCwaveH, ‘Simple tone'); 
DisposeHandle(waveH); 


end. 


The program FFSine Wave to Clip first allocates, from 
the heap, a handle to some data of the correct size. The mode 
and rate fields (rate works the same as in Four Tone mode) are 
set and then a sine wave for 22,200 bytes is calculated. The 
sine wave calculation is much the same as when we calculated 
a wave table for Four Tone mode. The index, i, changes from 
0 to 22199 and is multiplied by a frequency to obtain exactly 
1024 full cycles. The purpose of using two nested loops, one 
for the samples, and for the ticks, is so that we can present a 
graphical depiction of what is happening (one ticks worth at a 
time), When the WaveBytes array is filled we pass it to 
Wave, to. Clip. 


The first thing Wave to Clip does is to empty the 
clipboard of any prevoius data. This is the purpose of the 
ZeroScrap call (refer to the Scrap Manager chapter of Inside 
Mac). Then a BlockMove is done to move the ASCII bytes 
for WAVE' into a4 byte data structure (ResType-packed array 
[0..3] of char is not assignable in MacPascal). In another 
Pascal you could just say TheType:-"WAVE' Then the 
length of the data is found and the data is put into the scrap, 
using PutScrap. When I first started doing this I ended up 
with lots of Scrapbook items of type 'WAVE', and the 
Scrapbook window would say "no data of type TEXT or PICT 
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is available. There was no way of knowing what each 
Scrapbook item was. Then I found that if you put some 
TEXT on the scrap, then it would go along for the ride. This 
way the WAVEs in your scrapbook can have names. 
Therefore, when you call Wave To Clip you pass a string 
that will used to identify that wave. 


Now that we have a sound in our Scrapbook let's look at a 
program to play it. 
program Play. Clip. Wave; 

type 


Ptr = “integer; 
ParamBlockFake = arrayl0..30] of integer; 


MySynthH = ^MySynthP; 
MySynthP = “FFSynthRec; 


var 
waveH : MySynthH; 


TheType, offset, Size : 
str : str255; 


Longint; 


blockA, blockB : ParamBlockFake; 
AUsed : boolean; 


{ Paste MyStartSound here } 


begin 
ShowText; 
waveH := NewHandle( 12); 
str := ‘WAVE’; 
BlockMoveCéstr(1], @TheType, 4);{ TheType:='WAVE' ) 
Size := LinlineFC$A9FD, waveH, TheType, @offset); 
( GetScrap ) 


if size > Ø then 

begin 
repeat 
myS tar tSound(waveH*, size - 6, nil); 
until button; 


StopSound; 
DisposeHandleCwaveH); 


else 
writeln(C'no scrap of type ''WAVE'' is available'); 
end. 


As you can see there is hardly anything to it. Once 
TheType is set up we call GetScrap which fills the handle 
with the data and returns the size of the data. If no data was 
returned then size is zero. This happens when you forget to 
copy the sound from the Scrapbook before you start. 


I found two important things in the development of this 
routine. First of all, unless the length of the sound is an exact 
number of ticks, there will be a nasty click between each 
StartSound. This is because if the Sound Driver runs out of 
data, part way through the 370 bytes it is filling, it does not 
get the next sound right away. It waits until the next tick to 
pull the next sound command from the Device Managers I/O 
queue. Secondly, the examples in the Sound Driver chapter 
always pass sizeof(waveH™) to StartSound. This is very 
wrong. You should pass the length of the actual sound data 
and not include the mode and rate field in the length. This is 
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why we pass size-6 to myStartSound. Between the two of 
these I underwent a lot of grief (and missed my deadline) just 
to get the smooth, seamless, tone that FFSin_Wave_to_Clip 
and Play_Clip_Wave will make together. 


Want to make a different sound? Just change the 
calculation. If you put this (below) in the nested loops you 
get a loud hiss, like the inside of a jet, or an FM radio tuned 
to nothing. 


n :* random mod 256; 
waveH** .WaveBytes[i] := chr(n); 


I tried a different version of this that is much less wild. 
Instead of purely random numbers this (below) produces a 
wave form like a ‘drunks walk’. 


dics: 
:= n - (random div 8192); 
until (n >= 8) and (n <= 255): 


waveH^^ .WeveBytes[il : - chr(n); 


Surprisingly, it sounded almost the same as the first, only 
softer. Also, since no provisions were made for the wave to 
end at the same value at which it started (it wanders all 
around), there is a faint click every second. Various 
combinations of random noise and pure tones might produce 
interesting effects. Also, you could use these methods to test 
methods of digital filtering (although not exactly in real time), 
or novel forms of music synthesis. Novel waveforms could 
also be used, and tested, in the Four Tone mode. 


AS a final exercise I have attempted to produce the "endless 
scale" effect. The effect is supposed to be one of a sound 
continuously increasing in pitch without ever going off the 
scale. A sort of aural illusion. The way you produce it is to 
combine many tones, some high, and some low. When they 
all are mixed (added) together they sound like one single noise. 
Then, as they all smoothly move together upward in pitch, the 
higher notes are faded out as new low notes are faded in. In 
my attempt I use one pure tone for each of 5 octaves 
(musically, two tones are an octave apart if the frequency of 
one is twice the frequency of the other). I had to work quite a 
while on the math to get it so that the last few cycles of the 
wave exactly match those of the first few. I did it, but the 
result is a less compelling illusion than I had hoped. Even 
though there is no definable place where the sound starts 
again, or drops lower. If you want to see for yourself then try 
the following program. Be warned, it takes 105 minutes to do 
the entire calculation. It would be much faster if I had used 
tables for the sine calculations. 


I hoped you enjoyed this months expedition into the world 
of Macintosh sound, and I'll see you next month. 


program FF Endless.Scale. to. Clip; 
uses 


sane; 
const 
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WTSize = 22200; ( 370*60-0ne second of sound ) 


ptr = “integer; 


Handle = “ptr; 
MySynthH = “MySynthP; 
MySynthP = “MySynthRec; 


mySynthRec = record 
mode : integer; 
rate : fixed; 
WaveBytes : packed array[2..22199] of char; 
( WTSize bytes ) 
end; 


ver 

waveH : MySynthH; 

j, n, ticks, retraces : integer; 

i, pi, pi-div2, pi.div2.5, T : extended; 


engle, inc, Octave, period, Period div2 : extended; 


{ Paste Wave to Clip here } 


begin 
waveH :- NewHandle(WTSize + 6); ( size of mySynthRec ) 
wave", mode := FFMode; 
waveH**.rate := FixRatio( 1, 1); 


pi := arcTan(1) * 4; 

pi-div2.5 := pi / 2.5; 

pi-div2 := pi / 2; 

Period := 1 / 22200; 

Period.div2 := period / 2; 

inc := 2 * pi / 22200 * 256; ( 256 cycles/sec ) 
angle := Ø; 


ShowDrawing; 
textmodeCsrcCopy); 
128; 


n: : 
for ut := Ø to 59 do( 68 ticks ) 

n 

moveto(Q, 256 - n); 

for retraces :- Ø to 369 do( 370 retraces ) 


begin 
i := retraces + ticks * 370; 


angle := inc * Ci + Ci * i + i) * period_div2); 
T := Ø; 
Octave := Log2(1 + i * period) * pi_div2_5- pi_div2; 


for j := Ø to 4 do 

begin 
T := T + SinCangle) * (1 + SinCOctave)); 
angle := angle + angle; 
Octave := Octave + pi_div2_5; 


J 


n := num2integer(T * 32 + 128); 
vavel” b WaveBytes[num2integer(i)] : 
linetoCretraces, 256 - n); 
end; ( of retraces loop ) 
DrewStringCStr ingof (ticks)); 
end; ( of ticks loop ) 
Wave. to. C1ipCwaveH, 
DisposeHandteCwaveH); 


= chr(n); 


‘Endless Scale Waveform'); 


Pascal Procedures 


Mike Morton 
InfoCom 


Star Flight Graphics in TML Pascal Sm Flight Demo Cambridge, MA 


Star Flight: 
Real-time, 3-D animation on the Mac 


In the fall of 1984, I made the mistake of watching too 
much of a nine-hour “Twilight Zone” extravaganza. Most of 
that night was a blur, but I remembered one scene vividly — 
flying through space fast enough that the stars whizzed by. 
Today this effect is commonplace, appearing in everything 
from “Nightline” credits to “Star Trek” reruns. But it's 
usually done with expensive equipment and filmed one frame 
at a time. I wondered if a Macintosh could do the same 
thing... in real time. The result is an exercise in simple 3-D 
graphics and optimizing a Macintosh program. 


This article explains the program “Small Flight”, a subset 
of “Star Flight” (available through the Boston Computer 
Society's Mac group, or on the MacTutor source code disk 
#7). The reduced version is missing speed controls and special 
effects, but incorporates all the important internals of the 
Original program. 


Perspective 3-D graphics: 


“Small Flight” keeps track of star positions in a 3- 
dimensional space; each star has X, Y, and Z coordinates. The 
viewer looking at the Mac screen is looking along the Z axis 
in the positive direction. To simplify things, flying through 
space is done by decreasing the Z coordinate of each star, not 
increasing the viewer's Z coordinate. Thus the viewer is 
always at the origin. 


Where does the star at the 3-D point (X, Y, Z) appear on 
the screen? To find the location (h, v) on the screen, the 
formulas are: 


hzX*k/Z 
v=Y*k/Z 


“k” is a constant which determines how wide the view is. 
I used the maximum value of Z for k, and got a reasonable 
view. Try adding a control to vary k to see how it affects 
things. 


[For a more detailed explanation of perspective graphics, 
see Foley and Van Dam's classic Fundamentals of Interactive 
Computer Graphics. The above formulas are from chapter 8. 
You can derive them with a few sketches, using similar 
triangles.] 

implementation — the "star" data structure 
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A star needs very little information. At a minimum, its 3- 
D location (X, Y, Z) needs to be kept. “Small Flight" keeps 
X and Y in a Quickdraw point, and Z separately. The screen 
location is also kept when the star is first drawn, so it doesn't 
need to be recomputed when the star is erased. 


To initialize the data structure, the procedure “makestar” 
picks random values for X and Y, within a range. It always 
starts with the maximum value for Z. Then it derives the 
initial screen location and draws the star there. 


Implementation — moving a star 


The main loop repeatedly calls the "cycle" procedure to 
move every star. This routine loops through the array of 
records and processes each one. 


A given star is always erased, then its new position is 
computed. If the new Z coordinate is less than zero, the star is 
too close to see and a new random values are stored in that 
stars record. If the computed screen location is outside the 
view rectangle, the star is also out of sight and a new star is 
generated. 


Stars are always drawn as single pixels; this is done 
without Quickdraw. The program would be much slower 
using Quickdraw; I'm indebted to Dave Pearson of True Basic 
for suggesting the technique which is used instead. A 68000 
procedure “flippix” is passed the screen coordinates and toggles 
the bit in memory which corresponds to that point on the 
screen. The only complication is making sure the cursor 
doesn't interfere: the routine temporarily hides the cursor if it 
would be in the way, just as Quickdraw does. 


Optimizations in Star Flight 


Star Flight has lots of tricks to try to speed up the 
program, allowing more stars to be animated, but keeping the 
animation running fast enough to fool the eye. To make 
“Small Flight” presentable for educational purposes, I ripped 
out most of the tricks. To my embarrassment, the speed 
difference was nearly nil. Some speedups from both versions 
are worth describing: 


e the calculations for perspective were originally 
precomputed and stored in an array. This doesn't actually 
speed things up much, and slows down initialization a lot. 
It also limits the maximum X, Y, and Z values since 
arrays are limited in size. 
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e Since the Random function is expensive, I called it just 
once in the original “‘makeStar” and sliced up the result to 
get two random numbers. 


* Since "cycle" repeatedly refers to "stars[i]", it creates a 
pointer to the i'th star and avoids a lot of subscripting. 


e the code in "cycle" which checks if the star is outside the 
bounds rectangle could be done with a call to *PtInRect", 
but the explicit checks are faster. 


e avoiding Quickdraw is the most important optimization. 
Try removing calls to “flippix” and use "InvertRect" 
instead; see how much slower it gets! 


Enhancements in "Star Flight" 


The user interface which allows you to control the speed in 
the real “Star Flight" is easy to do. The menu commands just 
vary the variable “speed” (which is a constant in the scaled- 
down version) The only fancy thing is "warp" mode, in 
which stars leave trails; it'S just a flag which prevents stars 
from being erased. Try adding your own controls to the 
program; perhaps graphical ones would be better than the 
menus in "Star Flight"? 


Some projects you might consider: 


* make the stars cover the display uniformly, instead of 
clustering at the center. In a real spaceship, the density 
should be the same in any direction. 


e Similarly, avoid the “waves” of stars which occur in the 
first moments of flight. 


e when you leave “warp” on for a while in “Star Flight", 
patterns appear on the screen. I think this is because the 3- 
D coordinates have such a small set of discrete values. Try 
using larger values, but be careful not to overflow 16 bits 
in your calculations of screen location! 


* because the program makes no effort to keep in sync with 
the hardware screen refresh, you can sometimes see stars 
"twinkle". This is because the star is erased from memory 
and the screen is refreshed before the new location can be 
drawn in memory. This is more apparent when the star is 
moving upwards, since the refresh sweeps downwards. 
You could minimize this effect with a modified “flippix” 
which toggles two points, hoping to erase and redraw with 
as little time as possible in between. 


e to get smoother animation, you might try using the 
alternate video buffer. 


Of course, there are a lot of other changes. Add better 


navigation — roll, pitch, and yaw. Have the apparent size of 
a star change as it approaches! Introduce comets which don't 
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move in a simple path. Add Klingons and photon torpedoes... 
add a network hookup for multiple players... have fun! 


Putting It All Together 
by 
David E. Smith 


Small flight is written in TML Pascal, which is 
practically 100% Lisa Pascal compatible. The Pascal source 
may be compiled into a ".REL" file format or into assembly 
source code to be compiled by the MDS assembler. To get the 
Pascal to compile correctly under HFS, the include files and 
the source code file must reside in the same folder and on the 
same disk as the compiler. Version 1.1 of TML Pascal will 
fix some of these HFS dependencies and may be updated for 
$20 by contacting Tom Leonard directly. As is my practice, I 
compiled the pascal source into assembly source code, and 
then switched over to MDS to complete linking the code. 
[Note that you don't have to do it this way; I just prefer it.] 

The FlipPix routine is an assembly routine which flips the 
pixel on the screen to draw and erase the star directly. This 
routine could be very useful in a variety of applications where 
direct screen updating in assembly is required. Note that 
provision is made for the cursor! This routine is written in 
MDS assembly and is assembled by moving the assembly 
source code and all the include files to the same disk as the 
assembler, in the root directory (ie not in any folders). Again 
these HFS bugs are being fixed by Bill Duvall of Consulair, 
who is doing the update to MDS for Apple and which should 
be ready in April. In the meantime, Bill has released version 
4.52. of his smart linker and C system, which includes a fixed 
version of the editor and linker for HFS. Contact Consulair 
Corp. about updating the C package to version 4.52, and you 
will also gain an improved editor and linker for HFS that will 
work with TML Pascal. It is likely that Tom and Bill will 
cross license their two products so they can be sold as a 
compatible development system in the future; a marketing 
move we encourage both companies to adopt. In the 
meantime, they remain separate but equal in compatibility. 

The linker has the most problems under HFS. It won't 
recognize it's own link file! To get around this, click on the 
linker and then shift-click on the link file and select open from 
the file menu. This will start the link process. Then 
remember, again to have all the ".REL" files together on the 
same disk as the linker and not in any folders. Then the link 
process should proceed normally. 

The resource file is a simple assembly file that provides 
the basic Finder information to make a custom icon pop up on 
the desktop. You can create an icon with the icon editor and 
convert it to an "include" file by running Chris Yerga's icon 
converter program on it. Or you can use a DA called Icon 
Maker to create the hex code for the icon, or an icon resource 
directly. 

The link file combines the code files for the Pascal 
program, the FipPix assembly code, and the compiled resource 
file into a runnable application with the appropriate file 
attributes set to create the custom icon. The TML Pascal 
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creates an initial link file for you that you can then edit 
depending on what your doing. In this case, we edited TML's 
link file to include the FlipPix assembly routine. Note that 
unlike Microsoft's Fortran, the TML run time pacakge is fully 
MDS compatible! (We encourage Microsoft to fix up their 
buggy Fortran version 2.1 and make it fully toolbox and MDS 
compatible.) We continue to push for the MDS ".REL" file 
format as a standard which currently supports the MDS 
assembler, the Consulair C and TML Pascal as all linkable 
under the same linker, with Fortran almost there. That makes 
a considerable development system which we feel is the best 
way to go at the present time. It is our hope that other 
companies will work to establish a linking standard with these 
compiler products. 


program smallf light; ( a scaled-down "star flight" ) 
( Written by Mike Morton for MacTutor ) 
( Converted to TML Pascal by David E. Smith) 


($I MemTypes. ipas) ( 
($I QuickDraw. ipas} ( 
($I OSIntf.ipas ) ( 
($I ToolIntf . ipas ) ( 


TML Mac libraries ) 
Quickdraw interface ) 
Operating System interface ) 
Toolbox interface ) 


const 
numSters = 140; ( number of stars we display ) 
maxXY = 64; ( lergest star radius (X or Y) ) 
maxZ = 200; ( largest ster distance (Z) ) 
speed = 4; ( Z change per animation cycle ) 
type 
Star = record ( information about one star ) 
ploc: point; ( physical location in space (X, YO ) 
Z: integer; ( physical location in space (Z) ) 
sloc: point; ( location on the screen Ch, v) } 
end; 
ver ( global program variables ) 


sters:errey[£..numSters) of star; ( information on stars ) 


bounds: ^ rect;( rectangle used for bounds checking ) 

sorigin: point; center of screen ) 
myPort: X grefPort; ( our graphics environment) 
enevent: — eventrecord; ( for checking if the user's bored) 


procedure flipPix (h, v: integer); external; 
asm routine to flip pixel ) 


( mekestar -- randomize physical location; set Z and ) 
( find screen location. ) 
procedure makeSter (VAR new: star); ( initialize one star ) 
var dh, dv: integer; ( star's position, relative to origin ) 
begin; 
new.ploc.h := random mod maxXY; 
new.ploc.v := random mod maxXY; 
new.z := maxZ; 


( horizontal position ) 
( vertical position } 
( how far away is it? ) 


{ compute h offset } 
compute absolute h pos } 
( compute v offset ) 


dh := new.ploc.h*maxZ div new.z; 
new.sloc.h := sorigin.h + dh; ( 
dv := new.ploc.v*maxZ div new.z; 


new.sloc.v := sorigin.v + dv; ( compute absolute v pos ) 
flipPix (new.sloc.h, new.sloc.v); (flipspotCdraw star ist) ) 

end; ( of procedure makeStar ) 
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( initialize -- Do Mac initializations; calculate display 
rect; init } 
( screen; define bounds rect; draw initial stars. ) 
procedure initialize; ( one-time initialization ) 
ver i: integer; ( star number 


begin; 
initGraf(@thePort); ( fire up quickdraw ) 
openPort(@myPort); { get a drawing environment } 
initCursor; ( get rid of the Finder's "watch" ) 
bounds := screenbits.bounds; ( start with whole screen ) 


insetRect (bounds, 25, 39); ( shrink it ina bit ) 
ub ee := (bounds. left + bounds.right) div 2; ( find 
the... 
sorigin.v := Cbounds.top + bounds.bottom) div 2; ( 
„origin ) 
eraseRect (myPort.portRect); ( clean the screen } 
invertRect (bounds); ( space is black } 
offsetrect (bounds, -sorigin.h, -sorigin.v); 
( center bounds on origin ) 


for i := 1 to numStars do ( loop through all the stars.. ) 
mekeStar (stars [i]); { ...and make up each one } 
end; ( procedure init ) 


( cycl --main routine For each star, erase the old position.) 

( See ir its motion has carried it pest the plane we're in. 
If so, 

( we create a new ster. If not, we compute the new apparent ) 

( position from the new Z.Ifthe apparent positionis outside ) 
( display, we create a new star;otherwise we drew the ster's ) 
( new position. 


procedure cycle; 
var 


( do one animation cycle ) 


i integer; ( star number in main loop ) 
dv, dh: integer; ( star coordinates, origin-relative ) 


Sp: ^star; ( fast pointer to starsli] ) 
begin; 

for i := 1 to numStars do( loop through all the stars ) 

begin; 


Sp := 8sters(il; ( point to star (avoid subscripting) ) 
flipPix Csp^.sloc.h, sp*.sloc.v); 
erase the star's old position ) 


Sp^.Z :7 Sp^.z - speed; 
( time advances: find new z position ) 
if sp^.z <= 0 ( past the plane of the eye yet? ) 


then makeStar (sp^) ( yes: this star's gone; make 
another ) 
else begin; ( no: update star's screen position ) 
dh := sp^.ploc.h*maxZ div sp^.z;( compute relative h ) 
sp*.sloc.h := sorigin.h + dh; 
( and compute absolute screen h ) 


dv := sp^.ploc.v*maxZ div sp^.z;( compute relative v ) 
sp^.sloc.v := sorigin.v + dv; 
( end compute absolute screen v ) 


if (dv >= bounds.bottom) ( is the new position... ) 
or (dv <= bounds. top) ( ...outside... ) 
or (dh >= bounds.right2(..the bounds rectangle... ) 
or (dh <= bounds. left){ ...which is centered at 
origin? } 
then makeStar (sp*) ( yes, so get a new one ) 
else flipPix Csp^.sloc.h, sp^.sloc.v) 
no: drew it at new position ) 


end; ( of case where z didn't go off edge ) 
end; ( of loop through all stars ) 
end; ( of procedure cycle } 
begin; { main program } 


initialize; ( set everything up ) 
flushEvents Ceveryevent, 0); ( ignore stale events ) 
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repeat ( main loop: ) 
cycle; ( do one animation "frame" ) 
until getnextevent CmDownMask+keyDownMask, anevent); 
( until click or key ) 
end. 


flippix -- complement a pixel on the screen, given its 
global coordinates. 
procedure flipPix Ch, v: integer); external; 


Written by Mike Morton for MacTutor 
Converted to MDS Assembly by David E. Smith 
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xdef f lipPix 

include QuickEqu.D 

include SysEqu.D 

include ToolEqu.D 

include MacTraps.D 

MACRO „equ = equi ; convert lisa to mds 
MACRO -hideCurs = _HideCursor | 

MACRO _showCurs = _ShowCursor | 


CrsrRect equ $83C 


;SysEqu stuff 
grafGlob equ $0 


; parameter offsets from the stack pointer: 


bitH equ 4 ; horizontal pixel coordinate 
bitV .equ bitH*2 ; vertical pixel coordinate 
plast .equ bitV+2 ; address just past last 
peremeter 

psize .equ plast-bitH ; Size of parameters, in 


bytes 


; entrance: set up a stack frame, save some registers, hide 
; cursor if needed. 


flipPix: 
clr.w D2 


; clear flag saying cursor was 
hidden 


movem.w bitHCA7),D@/D1 ; load v. and h. coordinates 


; together 


, See if we'll need to hide the cursor while we draw 

lea CrsrRect+top, Ad ; point to rectangle the cursor 
;covers 
; compare v to rect.top 

; if too small Cabove r.top), don't 
;hide 

cmp.w CAQ)+,D1 » compare h to rect. left 

blt.s nohide; if too small Cleft of r.left), don't 


cmp.w CAG)+, DØ 
blt.s nohide 


jhide 

cmp.w CAG)+,DØ ; compare v to rect.bottom 

bge.s nohide ; if too large (below r.bottom), don't 
‘hide 

cmp.w CAQ)+,D1 ; compare h to rect.right 

bge.s nohide ; if too large (right of r.right, don't 
;hide 


-hideCurs; must briefly hide the cursor to draw here 

move.w #1,D2 ; flag that we did so 
nohide: swap D2; hidden or not: slide flag up to top of D2 
move.] grafGlobCA5), Ad 
move.] thePort(A0),AQ 
grafport 

mulu portBitstrowBytes(AQ),D@ ; v. times stride is 


; point to quickdraw globals 
; point to the current 


byte 
,offset of row 


move.b D1,D2 — ; copy h. coord Clow 3 bits) for bit 
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offset 
Isr.w #3,D1 ; extract byte offset 
add.w D1,DØ ; combine v. and byte component of h. 
not.b D2 ; make the bit® 68000-style (x 
:= 7-x) 
move.1 portBits+baseAddr(A®),A® ; pick up base address 
;of bitmap 
bchg D2,0CA0,D0 .w) ; flip the bit in the right 
byte 
swap D2 ; bring back cursor-hidden flag 
tst.w D2 ; is it set? 
beq.s return  ; no -- all done 
-showCurs ; yes -- show the cursor 
return: 


move.] CAT2*,AQ 
add.1 *psize,A7 
jmp (A0) 


; pop return address 
; unstack parameters 
; home to mother 


end ; Of procedure flipPix 


; Smallflight_rscs.asm 

; resource file for the Small Flight Program 
; created using the assembler 

; Signiture is creator tag 


RESOURCE '"SMFL' Ø 'IDENTIFICATION' 


DC.B 12, ‘SMALL FLIGHT' 
„ALIGN 2 
RESOURCE 'BNDL' 128 ‘BUNDLE’ 
DC.L 'SMFL ' ;NAME OF SIGNATURE 
DC.W 0,1 ;DATA CDOESN'T CHANGE) 
DC.L ‘ICN ; ICON MAPPINGS 
DCW Ø “NUMBER OF MAPPINGS- 1 
DC.W Ø, 128 ;MAP Ø TO ICON 128 
DC.L 'FREF ' ;FREF MAPPINGS 
DC.W Ø ;NUMBER OF MAPPINGS-1 
DC.W 0,128 ;MAP Ø TO FREF 128 


RESOURCE 'FREF' 128 'FREF 1° 
DC.B 'APPL', Ø, Ø, Ø 


„ALIGN 2 
RESOURCE 'ICN*' 128 ‘MY ICON' 


; FIRST APPLICATION ICON BIT MAP 
INCLUDE ICON.TXT 


IPAS$Xf er 


Link File 


/OUTPUT Small Flight Demo 
/Globals -4 


Small Flight 
FlipPix 
PAS$Sys 
OSTraps 

Tool Traps 


/TYPE 'APPL' 'SMFL' 
/ BUNDLE 

/RESOURCES 

SMALLFL IGHT. RSCS 
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Pascal Procedures 
Making Pascal Act Like Modula2 


Seperate Compilation with TML Pascal 

In order to develop large applications for the MacIntosh, 
it is desirable to have the capability to seperate your code into 
easily manageable pieces. This allows for modular 
programming and avoids having to compile all of your 
program each time which can be time consuming and 
frustrating for small changes. This article presents a procedure 
for doing this using the TML Pascal compiler. 

Theory 

The MDS linker (or Consulair's 'smart' linker) will take 
seperate 'REL' files containing the proper linkage information 
and combine them to create a stand alone application. What 
this procedure does is to describe the process of creating these 
REL' files. Basically, each module is a seperate Pascal 
program. The trick is to get the link files created properly so 
that the seperate modules will link together if one is changed 
and re-compiled. 

Example Program 

The example program below consists of three (3) seperate 
modules representing three segments of a single application. 
The first module (X modl.Pas) is the 'main' program. It 
contains the compiler directives necessary to create a 'LINK' 
text file for the LINKER. External references in segments are 
satisfied with : 

l. Include statements for standard symbols and declarations. 
(ie. ($I quickdraw.ipas. }.) 

2. Include statements for program globals (ie. ($1 
X_globals.ipas}) 

3. EXTERNAL procedure references. 

The external references will allow the compiler to 
‘assume’ the procedure exists and generate the appropriate 
temporary code. The actual addresses will be satisfied at link 
time. 

Scenario 
The following scenario describes the compile/edit cycle 
for the example: 
. Compile X modl.Pas. 
Compile X_mod2.Pas. 
. Compile X_mod3.Pas. 
. Link X_mod1.Link. (generated by X_mod1.Pas) 
. Run the application and discover a problem with 
X mod2.Pas. 
6. Edit X mod2.Pas and compile 'only' X. mod2.Pas. 
7. Link x modl.Link 
8. Verify application runs properly. 
Hints 

These hints are a result of experience. 

1. Occasionally an unidentified character will 'creep' into a 
text file which the compiler cannot recognize. The Pascal 
statement will look correct but the compiler will not 
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accept it. To see the offending character, use the 'SHOW 
INVISIBLES' option in the MDS editor. It is usually a 
'box looking' character. Just delete it. 

2. Since the 'main' program module creates the LINKER file, 
you have to 'force' the compiler to generate the linker code 
for the runtime packages that are used in the other 
modules. (ie $PAS files). This is done by putting in a 
Pascal statement in the main program that will invoke a 
runtime package. Example .. 'Concat will invoke the 
runtime package $PAS$Str package). 

Epilogue 
This procedure will allow you to create an application of 
essentially an unlimited size using the TML Pascal compiler. 

For large applications, this procedure is essential. It is good 

programming practice to plan ahead. 

PROGRAM X_mod iC Input, Output); 


($1 MemTypes. ipas) 
($I QuickDraw. ipas) 
($1 OSIntf .ipas) 
{$I ToolIntf . ipes) 
($1 PackIntf. ipas) 
($T APPL RABS) 

($8* 


($I X.globals.ipas) 

($U« X_mod2/Code) 

($U« X. nod3/Code) 

PROCEDURE — P.modi.proci Cv.var1 : Str255) ; FORWARD; 
PROCEDURE P_mod2_proci (v.vari : Str255) ; EXTERNAL; 
PROCEDURE P_mod3_proc! (v_var1 : Str255) ; EXTERNAL; 

PROCEDURE — P-modi.proc2 (v.varl : Str255) ; FORWARD; 


PROCEDURE P.mod1. proci; 
BEGIN 
writeln (v_var1); 
writeln C'In P. modi. proc1'); 


a 


( 
(== P_modi_proc2 (v_var1 :Str255) == 


PROCEDURE P_mod1_proc2; 
BEGIN 


writeln (v_var 1); 
writeln C'In P_mod1_proc2'); 


ie 
(== execution begins here == 
BEGIN 

g-global! :- 000; 

REPEAT 


P.modl proci C'From modi main'); 
P_mod2_proci C'From modi main'2; 
P-mod3. proci C'From modi main'); 


writeln; 
writeln ('Type a 999 to quit, any other number to 100p'); 
Readln (g_global 1); 


UNTIL (g-global1 = 999); 
END. 
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PROGRAM X_mod2( Input, Output); 


($I MemTypes. ipas) 

($1 QuickDraw. ipas) 

($1 OSIntf. ipas) 

($I ToolIntf . ipas) 

($I PackIntf . ipas) 

($I X_globals. ipas) 

PROCEDURE P_mod2_proc! (v_var1 : Str255); FORWARD ; 
PROCEDURE P_mod3_proc! (v.var1 : Str255); EXTERNAL; 
PROCEDURE P_mod2_proc2 (v_var1 : Str255); FORWARD ; 
($S Code) 


PROCEDURE P_mod2_proc1; 
BEGIN 

writeln (v.var 1); 

writeln C'In P.mod2.proc1'); 
END; 


PROCEDURE P_mod2_proc2; 

BEGIN 
writeln (vvar 1); 
writeln C'In P_mod2_proc2'); 
D: 


END; 
($S main) 


PROGRAM X_mod3CInput, Output); 


($1 MemTypes. ipas) 

($1 QuickDrew. ipas) 

($1 OSIntf. ipas) 

($1 ToolIntf . ipas) 

($1 PackIntf . ipas) 

($I X_globals. ipas) 

PROCEDURE P_mod3_proci (v.var1 : Str255); FORWARD; 
PROCEDURE — P.modl proci (v_var1 : Str255); EXTERNAL ; 
PROCEDURE — P.mod2 proc! (v_var1 : Str255); EXTERNAL ; 

PROCEDURE P_mod3_proc2 (v.vari : Str255); FORWARD; 


ies Code) 
(== P_mod3_proc! (v_var1 : Str255) = 
PROCEDURE P_mod3_proc1; 
BEGIN 

writeln (v. var 1); 

writeln C'In P. mod3. proc1'); 
(== P_mod3_proc2 (v.vari : Str255) =} 


PROCEDURE P_mod3_proc2; 
BEGIN 
writeln (vvar 1); 
writeln C'In P_mod3-proc2'); 
END; 
{$S main) 
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File of Global Variables 


g-global1 : INTEGER ; 
g-global2 : Rect P 


] 


] ] 


IPAS$Xf er IPAS$Xf er IPAS$Xfer 


X-Mod1 X_mod2 X_mod3 
PAS$Sys PAS$Sys PAS$Sys 
OSTraps OSTraps OSTraps 
ToolTraps ToolTraps ToolTraps 
PackTraps PackTraps PackTraps 

( ( ( 
X_mod2/Code X_mod2/Code X_mod3/Code 
( ( ( 

X_mod3 /Code X_mod2/main X_mod3/main 
PAS$StdIO PAS$StdIO PAS$StdIO 
Dec2Str Dec2Str Dec2Str 


Str2Dec Str2Dec 


Link File #2 


Str2Dec 
Link File #3 


Link File #1 


From modíi.main 
In P-modi. proci 
From modi_main 
In P-mod2. proc 
From modí.main 
In P_mod3_proc 1 


Type a 999 to quit, any other number to loop 
7 


From modíi.main 
In P-modi. proc! 
From modi. main 
In P-mod2- proc 
From modi. main 
In P_mod3_proc 1 


E Type a 999 to quit, any other number to loop 


Fig. 1 Combined program output 


Pascal Procedures 


Alternate Video Screen Animation 


Introduction 

This article discusses using the Mac's alternate hardware 
screen to get smooth, flicker-free animation. We'll use the 
“vertical retrace manager” to synchronize screen-switching 
with the hardware screen refresh. The subroutine package 
presented does this synchronizing and helps the calling 
program ensure that it's drawing animation frames at the 
desired speed. It also tells the program how much “slack” 
time it has after drawing each frame. The source for a simple 
bouncing square demo program which uses the subroutines is 
included here. Another program, *Vanlandingham", uses the 
same package to mimic Amiga's famous bouncing ball demo, 
but its source is too convoluted to publish. Both applications 
are distributed on MacTutor's source code disk #9. 

Hidden Gotcha 

Warning: These programs use the alternate screen buffer, 
an area of memory that is also used by the Mac Plus RAM 
cache. As a result, when the program exits, Finder information 
previously in the cache will be lost causing a system crash. 
To prevent this, turn off your RAM cache with the control 
panel. It's possible to design an interface to let the system 
know your application is using the alternate video buffer, 
forcing the Mac to configure the cache somewhere else. We 
invite readers to investigate how this might be done. For 
similar reasons, this program doesn't work with all software or 
hardware. It may not like RAM disks, debuggers, or some 
hard disks. As with any application which doesn't have a QA 
group to test it, you should back up your files and take other 
precautions before trying it. 

The animation package uses two slightly obscure features 
of the Mac, one in hardware and one in software. The 
hardware feature is the alternate screen, a second bitmap in 
RAM which can be displayed instead of the default one. The 
software feature is the vertical retrace manager, which calls 
subroutines periodically, in sync with the “vertical retrace 
interrupt", &sort of hardware heartbeat in the Macintosh. Both 
of these arécovered only briefly here, since they're documented 
elsewhere. 

. Quick review #1: The alternate screen 

The Mac hardware redraws the screen 60 times a second, 
repeatedly reading the screen from RAM and interpreting bits 
as black or white pixels. By default, it reads from a hardwired 
address, ‘available from the base address of Quickdraw's 
"screenBits" bitmap. The hardware can also read from a second 
address, 32K lower than the default, and software can request 
that this alternate screen (sometimes called the alternate video 
"page" ) be used. 

A simple animation program: without the second screen 
just repeatedly erases and redraws images. The problem with 
this is that the hardware "strobes" the image in RAM at 
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Fig. 1 Bouncing Ball from “Vanlandingham” 
program 
unpredictable times. 
animation frames and the software can get caught with its 
pants down. The result is flicker. 
A better solution is to use two screens. 
displays one screen while the next animation frame is drawn 


The bitmap may be strobed between 


The hardware 


on the other. Software can detect when the current screen 
refresh is complete, and ask that the next refresh be drawn 
from the newly drawn bitmap. Then while that bitmap is 
showing, the original bitmap can be erased and filled with 
another frame. This way, drawing and display always use 
different screens. The result is much less flicker. 

Apple didn't make it easy to use the alternate screen. The 
decision to configure the alternate screen is usually made by 
the program which launches you; the Finder won't ever do it, 
though. You can't reserve the second screen through 
traditional memory management after launch, because you 
can't specify the area to allocate. The generally accepted 
method of getting the second screen is to check whether it's 
available at startup and, if it's not, to re-launch oneself with a 
request for the second screen. (Of course, if the request ever 
fails for any reason, such a program will loop forever...) 

There are some problems to keep in mind when using the 
alternate screen: 

e future Macintosh models may not support it (the May 1985 
software supplement warned about this) 

* cursor handling seems to assume that the default screen is in 
use; do a HideCursor call before switching 

* you should switch to the main screen before exiting to the 
Finder 
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* Debuggers, RAM disks, and other things which survive 
across launches may occupy the memory where the alternate 
Screen is; this is hard to detect and avoid 

For more on the alternate screen, see Tom Taylor's article 
on the subject in the August 1985 issue of MacTutor. For a 
detailed description of the hardware, I recommend The IM 
Underground. The latter has some ideas on allocating the 
Screen. 

Quick review $2: Vertical retrace tasks 

The Mac operating system lets you leave “wake-up calls" 
for subroutines, allowing you to specify the delay (in 60ths of 
a second) before the subroutine is called. This is handy for a 
lot of things, including screen switching. 

Each time a screen refresh is completed, the Macintosh 
gets a “vertical retrace interrupt”. At this time, the system 
may perform several housekeeping tasks: updating the cursor 
position, bumping the tick count, and so forth. It also checks 
the list of subroutines which have left wake-up calls, seeing if 
it's time to call any of them. 

Vertical retrace tasks, as these dozing subroutines are 
called, are pretty simple. The chapter of Inside Macintosh 
which describes the vertical retrace manager is just a few 
pages. Ignoring a few fields, the essential parts of the “queue 
block” for the task are (1) the address of the routine and (2) the 
time left until it should be called. 

The exact time at which these routines are called is 
perfect for switching screens. It happens between screen 
refreshes, so the switch doesn't occur halfway down the screen 
(giving you a fleeting split image). [It is possible for many 
time-consuming retrace tasks to be called, and for the switch 
to be delayed until after the refresh has started. This is very 
unlikely.] 

Some problems crop up in calling routines this way. 
The most insidious appears randomly when someone alters 
AS. This is legal as long as they don't call anyone who 
expects AS to be correct. If an interrupt comes in while AS is 
changed, the system will call the retrace tasks with the WIOng 
value of A5. It's up to each task to either load the correct 
value from "CurrentA5" in low memory or not use AS at all. 
Recent versions of Inside Macintosh describe the OS Utilities 
"SetUpAS" and "RestoreA5" which can be used to avoid this 
problem in Pascal. Note that even if your application doesn't 
mess with A5, desk accessories and the ROM still may. Be 
paranoid. 

Lesser problems with vertical retrace tasks include: 

you should make sure that your task is gone from the queue 
before leaving the application; otherwise someone else's 
code (such as the Finder's) will be loaded over the task's old 


address and the vertical retrace manager will call that address 


with horrifying results 
your task can't perform any memory management, since the 
state of the heap may not be consistent; in general, you 
must be careful about any operations on global data 
Structures 
the task must set its “alarm” each time it's called, or it 
won't be called again 

Inside Macintosh covers the vertical retrace manager 
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pretty well. Robert Denny's article in the August 1985 
MacTutor gives a good example of using these tasks. 
Putting it all together 

Here's a package to synchronize screen switching. It has 
three subroutines: 

getaltscreen — This should be the first thing your 
application calls. It checks whether the alternate screen is 
configured and, if not, relaunches the application to include the 
Screen. 

This routine is independent of the other two. 

vidstart — This installs a vertical retrace task which 
runs at the frequency you choose. The caller and these 
subroutines share a structure used to pass information both 
ways. 

To switch screens, the application stores a request in the 
shared information block. The video task wakes up, finds the 
request, switches the screen as appropriate, and flags that 
there's no longer a request pending. 

There are four states for the request field: 

0: request for alternate screen is pending 
1: request for default screen is pending 
2: request to stop the task is pending 

3: no request is pending 

Ideally, the task wakes up at the end of each cycle, finds a 
pending request and performs it. But what if there isn't a 
request pending? That's fine — the task just sets an alarm to 
re-examine the request one tick from now (not one whole 
cycle, which could be many ticks) and tries again. This way, 
even if the next frame isn't ready on time, it'll be displayed at 
the first possible retrace interrupt after it becomes ready. 

When the task discovers this situation (an animation 
cycle has elapsed but no request was stored), it means the main 
program didn't draw its next frame in time. The programmer 
needs to know that this happens, so these events are kept track 
of in the “delays” field in the information block. The program 
doesn't have to examine the counter, but you may want to 
print it periodically while you're developing the program, to 
make sure the animation rate is what you expect. 

vidwait — Suppose a program finishes drawing a frame 
on the alternate screen and stores a request to show that screen. 
The next thing it wants to do is draw the next frame on the 
default screen. But it can't yet — it has to wait for the switch 
so that the default screen is no longer being displayed. This is 
easy: when it sees the request flag is in the “no request 
pending" state then it knows the task has done the switch. 
The vidwait routine waits for this to happen. You should 
always call it before drawing a new frame. 

As mentioned above, the task notices whether your 
drawing code is fast enough to keep up with the screen 
switching task. But suppose you try a new drawing method to 
see if it'S faster. You run both methods, and both keep pace 
with the task. Can you measure the speed of the tasks more 
finely? Yes: vidwait does it by counting how many times it 
loops while waiting for the request to be done and returning 
the count. A larger count means more slack time between the 
drawing and the screen switch, which means the drawing code 
is faster. This kind of fine tuning helped in getüng the 
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bouncing ball to run at 60 Hz. 
Notes on the subroutines 

The information block, which is defined by the main 
program and passed to the subroutines, includes a task block 
for the vertical retrace task. It also has the request field, the 
period (number of ticks between screen switches), and the 
counter used to keep track of delays. 

The problem of whether AS is valid is bypassed by 
making the information block contiguous to the VBL task — 
the system passes a pointer to the task block when it calls the 
routine, so the information block is easy for the task to find. 

When the task sees a request to stop (probably because 
the application is quitting) it doesn't call VRemove; tasks 
shouldn't dequeue themselves. Instead, it clears the "count" 
field of the task block, telling the system not to leave it in the 
queue. 

Notes on the sample application 

The application which demonstrates these routines is 
pretty dull. It bounces a square around the screen until it 
detects a key press or mouse click. 

The constant "tickrate", the number of ticks per frame, is 
set to 1, so the animation rate is 60 Hz. I was surprised that 
30 Hz didn't look smooth. (Perhaps 30 Hz would look better 
if the image was more complex and distracting to viewers.) 

You can play with the animation rate and the block 
should move at the same speed — the velocity (in real time) 
should be independent of the animation rate. 

The program must keep track of where the block was last 
drawn in the default and alternate screens. The rectangles 
"deflast" and "altlast" are used for this, so that the code knows 
what area to erase before drawing the next block. 

Ive commented out the statistics code used to keep track 
of whether the animation is at the desired rate. It may need 
changes if you're not using Lisa Pascal (as I was before this 
was translated to TML Pascal). [The statistics procedure is 
here, but printing code is left to the user to implement. -Ed] 


Fig. 2 Our bouncing square demo program 
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Printing statistics was a problem: each time I printed a 
line, it caused some delays, which the program reported the 
next time. This is like physics: observing affects the thing 
being observed! I couldn't stop the interference, so I made the 
printing occur with exponentially decreasing frequency: it's 
done after 256 frames, 512 frames, 1024 frames, etc. (Check 
out the code that checks for a power of 2!) The average 
number of delays per sample will approach zero if the delays 
are only an artifact of the debugging. 

Before stopping, the program makes sure the task is 
stopped. The request to stop makes the task deactivate and 
also returns to the default screen to keep the Finder happy. 
(Remember, a RAM cache on a Mac Plus will not be happy, 
since some vital Finder info will be destroyed by the use of 
the alternate screen buffer.) 

You may want to vary the size of the block, to see how 
large you can make it before the drawing takes too long and 
delays start getting recorded. This may vary slightly between 
Pascal compilers, but isn't a very exact benchmark. For those 
advanced programmers, try to come up with a technique so 
that even the RAM cache will be spared. 

Program Compilation 

[To implement the source code listed here, use either the 
MDS assembler or Consulair C 4.53 to edit and assemble the 
assembly language subroutines into a ".REL" file. Then 
compile the Pascal source code for the bouncing square demo 
using TML Pascal 1.11 or later. The link file shown here can 
be used with either the TML Linker or the Consulair Linker. 
Both linkers can apparently recognize and open object files 
created by the other. As reported previously, we have been 
using the Consulair C as an assembler until Apple updates the 
MDS system to work correctly on a Mac Plus. The link file 
will link the assembly subroutines with the Pascal source to 
create the final application. Three system files from the Pascal 
system are required. These are the Pas$Library package, and 
the OSTraps and ToolTraps ".REL" files. Once you figure out 
how to satisfy everybody's interpretation of how to construct a 
path name to the include and system files, the compilation and 
linking are easy. 

We must remark that Apple apparently forgot that some 
programs, like development systems, must have a way to find 
specific files without a user dialog. The HFS system makes 
every folder an independent directory with no provision for 
searching everything for a certain file. In fact, even if such 
provision were made, you would have problems because files 
can now have the same name if in different directories 
(folders), so how would you know you got the right file? This 
omission is causing fits for language system developers trying 
to figure out the best way to tell their compiler where to find a 
run time package, include file or "REL" file. The result is 
everyone is making up their own solution to this problem, 
destroying the standardization of the Mac interface. Give Apple 
a slap on the wrist for over-looking this problem.-Ed] 

Summary 

The alternate hardware screen can help create rapid 
animation; switching screens at the right time can avoid 
flicker. A regular task called in sync with the screen refresh 
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can make switching between screens very easy. 

An animation program under development needs to keep 
track of whether its animation is running at the desired rate and 
how much spare processing time remains in each animation 
cycle. Both of these are easy to record, although sometimes 
hard to report. 

There are a variety of pitfalls in the alternate screen and 
the vertical retrace manager. Probably the most significant 
one for serious applications is that the alternate screen may 
disappear in future Macintoshes. Still, if you're doing 
animation more for fun than for profit, it's worth the extra 
effort to get smooth animation. 

vid -- Routines to synchronize switching between the two 


hardware screens in sync with the screen refresh, allowing 
smooth animation. mike morton, June 1986. 


Wwe We Vo 


function vidwait 

procedure vidstart 
CVAR block: vidinfo; period: integer); 

procedure getaltscreen; external; 


CVAR block: vidinfo): longint; external; 


we We 


external; 


we 


MDS or Consulair Assembler Version. 
Converted by David E. Smith for MacTutor. 


we We 


xdef vidwait 
xdef vidstart 
xdef getaltscreen 


Include QuickEqu.D 
Include SysEqu.D 

Include ToolEqu.D 
Include MacTraps.D 


; MDS toolbox equates and traps 


MACRO .equ = equl ; convert Lisa stuff to MDS Mac 
MACRO -hidecurs = _HideCursor | 
MACRO .showcurs = .ShowCursor | 


; definition of state information record. 
; Also defined on Pascal side. 


vblsize  .equ vblphese*2 ; Size of VBL block 

ivb] „equ ð ; VBL task information 

ireq .equ ivbl*vblsize ; Cint) request: 
,alt/default/stop/none 

iperiod .equ ireqt2 ; Cint) period in ticks 

idelays .equ iperiod+2 ; Clongint) number of times 


jwe had to delay for a tick 
isize „equ idelays+4 ; Size of “info” block 
$104 ; VIA base address global 

$936 ; alt screen page global 


viebese equ 
CurPage .equ 


; request definitions: the high level code saves these for us 
; *** note: the code at “vb1” depends on these values. *** 


reqalt „equ 
reqdef „equ 
reqstop  .equ 
reqnone .equ 


9 ; request switch to alternate screen 
| ; request switch to default screen 

2 ; stop on default screen 

3 ; nothing requested 


; function vidwait (block: ptr): longint; external; 

; this routine is called when the next animation frame is ready 
; to be shown and the main program has made a request to 

; display that frame. it waits until the new frame is being 

; Shown, then returns. it also returns the 

; approximate time it had to wait, in arbitrary units. this 
helps 

; you find out how much slack you have between the time the 
frame is ready and the time it's actually used. 
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vidsait: 
move.) (SP)+,Al ; pop return 
move.1 (SP)2*,A0 » pop block pointer 
moveq  *-1,D0 ; will be Ø if we exit right away 
vidw2: 
addq. 1 81,D0 ; bump spinning counter 
cmp .W freqnone, ireqC Ad) ; is nothing waiting? 
bne.s vidw2 ; Something pending: 
; don't return yet 
move.1] DØ, CSP) ; return “time” waited 
jmp (A1) » return 


j procedure vidstart (block: ptr; period: integer); external; 


vidstart: 
move. | 
move .w 


6(SP), Ad 
4(SP), DØ 


; point to VBL block 
; pick up desired period 


move .w 
move .w 
clr.1 


"reqnone, ireq(AQ) ; initialize req info “none” 
DØ, iperiod(A0) ; save period 
idelaysCA2) , no delays seen yet 


move.w "vType,vblTypeCAB) ; set type of queue elem 
lea vb1,A1 ; point to VBL routine to call 
move.] Al,vblAddr(A2) 
move.w  D9,vblCountCA0) 
clr.w  vbliPhaseCA0) 


; save address of routine 
; Set time to wait 
; zero phase 


-vInsta11 
tst.w DØ 
bne.s 


; install the vertical retrace task 
; good status? 
death ; no: bag it 


61 move.] (SP)+,A9 ; pop return 
addq.] %4+2,SP ; 
jmp (A0) 

) 

; this is our entry point from the vertical retrace manager . 

; entered by: AØ points to VBL block; our state information 

; follows this. 


3 

; 7 if no request has been made by the time we're called, the 
main program didn't have a frame to be drawn in time; in this 

, case, we increment the “delays” counter and set the alarm 

; to wake us up one tick from now. 

"ife request is there,we do it and set the alarm for one full 

, period. 


vbl: 
move.w ireqCA0), DØ ; pick up the request 
move .w ®reqnone, ireq(AB)  ; cancel pending request 
move.| viabase,Al; point to base of VIA stuff 
dbra D8,vb11; skip if not zero 
bclr — 56,$1E00(41); alternate screen: clear bit 
move.w iperiodCAQ), vb1Count( Ad) 
; ask for next wake-up at usual time 
rts ; exit 
vb11: 
dbra DØ, vb12 , wasn't zero; skip if not one 
bset "6, $ 1E00(A1) , default screen: set the bit 
move.w  iperiodCAD),vblCount(A0) 
, ask for next wake-up at usual time 
rts ; ta de 
vb12: 
dbra D8,vb13  ; wasn't zero or one; skip if not two 
clr.w  vblCount(A2) ; stop: don't want to run again 


bset — "6,$1E00(A1) ; default screen 
rts ; home for the last time 
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vb13: 


dbra DØ, death ; wasn't 9,1, or 2; die if 
not three 
move.w f 1,vblCount(A2) X ; no request: re-run 
edd.]  *1,ideleysCA0) ; keep stats on 
how often 
rts ; and return 
death: DC.L  $60FE  ; execute a loop - stall 


4 

; procedure getaltscreen; external; 

; this should be the VERY first thing your application calls. 
; 7 if the alternate video screen IS configured, we return and 
; do nothing. 

; 7" if the screen isn't there, we find out the 

; epplication's name from the application parameters and 

; relaunch ourselves, correctly configured. 


getaltscreen: 
tst.1  CurPege ; pick up current screenconf iguration 
bpl.s relaunch ; negative means we got alt. screen 


rts ; all's well; return 


relaunch: ; here when we have to restart 
sub.1 %32+4+2,SP ; for Name, RefNum, Param 
move.] SP,AQ ; point to base of this stuff 


pea 4*2CA0) ; push arg: VAR pointer to apName 
pea ACAD) ; push arg2: VAR ptr to apRefNum 
pea 9(A0)  ; push erg3: VAR pointer to apParam 
-GetAppPerms; fill in name, other junk; pop params 


; Now apParam, apRefNum and Cimportantly) apName are 
; in stack temps. 


lea 4+2(SP), Ad 
move. | 
move. 1 
move. | 
-launch 
bra.s 


; point to the name we just got 

#-1,-(SP); -1 asks for alternate screen... 

AB, -CSP) ; ...8nd point to name to launch 

SP,AS  ; point to name ptr and flags with Ag 
; launch ourselves, with alt screen 

death — ; shouldn't reach here! 

end 


( viddemo -- A simple program to demonstrate the "vid" 

routines, which allow switching between the default and 
alternate video screens in sync with the screen refresh, 
allowing flicker-free animation. mike morton, may 1986) 


program viddemo; 


($i MenTypes.ipss ) 
($i QuickDraw. ipas 
) 


( demonstrate screen-switching ) 


(TML Pascal include files) 


($i OSIntf . ipas 
($i ToolIntf . ipas 


const 
tickrate = 1;  ( ticks between animation frames ) 
width = 129; ( size of the moving square ) 

( Parameters for the “vidinfo.request” field. ) 
reqalt = Ø; ( request switch to alternate screen ) 
reqdef = 1; { request switch to default screen } 
reqstop = 2; ( request default screen; stop task } 

type 


screentype =(default, alternate); ( current screen? ) 
vidinfo = record ( data structure *vid^ routines } 

v: VBLTask; ( the vertical retrace task block ) 
request: integer;  ( current request:alt/def /stop/none ) 
period: integer; ( ticks between fremes ) 

delays: longint; ^ ( number of delays observed ) 

end; | 


ver 


myPort: grafPort; ( our graphics environment ) 


vh, vv: integer; ( velocity: h and v components ) 

blockrect: rect; ( rectangle for bouncing block ) 

boundsrect : rect; ( rect in which block bounces ) 
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anevent: eventrecord; ( for awaiting keystroke or click ) 
theinfo:  vidinfo; ( info shared with vid routines ) 
altbits: bitmap;  ( bitmap for alternate screen } 
whichscr: screentype; ( on alternate/default screen? ) 
deflest, altlast: rect; { rectangle we last drew in ) 
zot: longint; ( throwaway result, functions ) 


totfreetime: longint;( statistics: accumulated free time ) 
samples: longint; ( statistics: number of samples ) 


function vidwait — (VAR block: vidinfo): longint; external; 
procedure vidstart (VAR block: vidinfo; period: integer); 


external; 

procedure getaltscreen; external; 
procedure init; ( initialize everything ) 
begin; 
InitGraf(@thePort); ( fire up quickdrew ) 
OpenPortC@myPort); ( get a drawing environment ) 
InitFonts; ( for writelns ) 
InitCursor; ( set the arrow cursor ) 
HideCursor; ( but we don't want it ) 


boundsrect := screenbits.bounds; 


( display rectangle is full screen.. } 
InsetRect (boundsrect, 15, 15); {( „inset a bit ) 
SetRect (blockrect, Ø, Ø , width, width); 
( make up rect for square ) 
OffsetRect (blockrect, 15, 15); 

( start it in the bounds rectangle ) 


altlast := blockrect; — ( init “old” positions ) 
t := 


def las blockrect; 
eltbits := screenbits; { alt. screen is the usual, but.. ) 
with altbits do ( [anything to fit in 80 
columns!] ) 

beseaddr := qdptr Clongint(baseaddr) - 32768); 


( base is 32K less ) 


EraseRect (thePort* .portbits.bounds); 
( erase the usual screen } 


FillRect Cboundsrect, gray); 
l draw the boundary we bounce in ) 


CopyBits (screenbits, altbits, screenbits.bounds, 
altbits.bounds, srcCopy, NIL); 

whichscr := default; ( start out on the default page ) 

vh := 5 * tickrate; 

vv := 3 * tickrate; 

samples := Ø; 

totfreetime := 9; 

vidstert Ctheinfo, tickrate); 
( stert screen-switch task running ) 

end; ( of procedure init ) 


( pick any old speed.. ) 


( initialize statistics ) 


( showstats -- Print statistics in whatever way you like. 

I don't print them until there are a fair number of samples 
accumulated. Also, the code below prints stats only when 
the number of samples is a power of two, so the frequency 
of debugging output decreases exponentially. ) 


procedure showstats (samples, totfree, delays: longint); 
begin; 
if samples > 200 
then begin; ( don't print for a while ) 

( The odd “if” below makes us print only 

when “samples” is a power of 2. ) 

if BitAnd (samples, -samples) = samples 

then begin ; 

(print routines go here} 

end; 
end; 
end; ( procedure showstats ) 


( animate -- Prepare and display the next frame of animation. 


© The Complete MacTutor, Vol. 2 


Compute the new position of the block, including bouncing if whichscr = default ( currently showing default 


off the walls. Wait for the video switcher to finish screen? ) 
displaying then begin; ( yes: next frame is on alt 
one page so we can draw in it. Set Quickdraw to drawing in Screen 
SetPortBits Caltbits); 
erase the last block drawn and draw the new one. Tell the ( make Quickdraw draw on alt. bitmap } 
video switcher we're ready to have this newscreen shown.) FillRect Caltlast, gray); ( clean up last place we drew ) 
altlast := blockrect; ( remember where we're 
animate; ( drew the next position drawing now ) 
FillRect Caltlast, black); ( and draw new image ) 
d freetime: longint; ( delay before switch is done oe := alternate; ( remember where latest image 
is... 
begin; theinfo.request := reqalt; ( .and ask vid switcher to 
OffsetRect Cblockrect, vh, vv); { move to the next show it } 
position } end ( end of doing frame on alt screen ) 
else begin; { no: next frame is on default 
( These four *if^s all check if the block has gone outside screen j 
the SetPortBits Cscreenbits); ( point Quickdraw to default 
bounds rectangle. If so, the block is adjusted in the screen } 
appropriate direction (v or h), and a velocity component FillRect Cdeflast, gray); ( erase last image we drew ) 
(vv or vh) is negated. } "ida := blockrect; ( remenber where we're putting 
block 
if blockrect.bottom > boundsrect.bottom ( bounce off the FillRect Cdeflast, black); ( put it there ) 
bottom? ) whichscr := default; { remember which screen is 
then begin; displayed } 
OffsetRect(blockrect, Ø, 2 *(boundsrect.bottom- theinfo.request := reqdef; ( ask video switcher to show - 
blockrect.bottom)); default ) 
vw := - wW; end; { of branching on which 
end; screen } | 
end; ( procedure animate ) 
if blockrect.top « boundsrect.top ( bounce off the 
top?) — begin; ( MAIN PROGRAM ) 
ser an, t (blockrect, Ø, 2 * (boundsrect.top- getaltscreen; (first, get the alternate screen ) 
se Une SEKEBG S): Ma SUDdSh ect; top init; ( now initialize everything else ) 


blockrect.top)); FlushEvents Ceveryevent, Ø); { ignore old clicks, etc. } 


vv := - w; 

end; repeat ( loop repeatedly ) 
enimate; drew next animation frame 
Me def « boundsrect.left  { bounce off the until GetNextEvent (nDownMask + keyDownMask, enevent); 
then begin; theinfo.re = 
E request := reqstop ( exit on default page ) 

b] A RE 2 * (boundsrect. left zot := vidwait (theinfo); ( make sure last request done } 

wh is “yh; po end. ( of main program ) 
end; 
if blockrect.right > boundsrect.right ( bounce off the IPAS$Xfer 
right? ) ] 
then begin; ) 

OffsetRect Cblockrect, 2 *(boundsrect .r ight- /Globals -4 
blockrect.right), Ø); /OUTPUT video 

vh := -vh; 
end; viddemo 

vidstuff 

freetime := vidwait Ctheinfo); ( wait for page to switch ) PAS$L ibrary 
totfreetime := totfreetime + freetime; ( keep track of total ToolTraps 
wait. ) OSTraps 
samples := samples + 1; ( „and number of samples in 
average ) $ 


showstats (samples, totfreetime, the info.delays); 


Fig. 3 Link File 
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Pascal Procedures 


Introduction to Definition Routines 


Introduction 

This is the first of a series of articles which will cover 
Macintosh Definition Routines. I will use TML Pascal for all 
the programming examples because it is rapidly becoming the 
most popular Development System on the Mac, and because 
the new TML linker will allow you to create procedure 
resources (MDEFs PROC's WDEF's FKEY's ect.) quickly 
and efficiently. 

This month I will cover the issues in common to all the 
different types of definition routines. In the following months 
I will cover Menu definition routines (MDEF's), Window 
definition routines (WDEF's), Control definition routines 
(CDEF's), List definition routines (LDEF's), and function key 
routines (FKEY's) in depth. 

Defintion routines allow you to create a variation of a 
standard type of "Object" to better fit your needs. That is, 
they effect the general appearance and behavior of whatever 
they define. The pattern selection Menu in MacDraw is a 
good example of this. Definition routines are usually stored 
as resources but they may also be set up as routines within 
your program. | 

The best way to develop a Definition Routine is to make 
it a routine in your code, and when its finished, to compile it 
into a resource which can then be used with any application. 
The Menu, Window, Contol, and List managers all allow you 
to use definition routines. 

Getting a Handle On Things 

When you create a new object (menu, window ect.), you 

can specify a non-standard definition routine (a routine other 


Pattern 


Fig. 1 A non-standard Menu Item 
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than the normal Mac ROM way of doing something) for it to 
use. There are two ways of doing this. 

1. By making the procedure a resource in a 

seperate file. 


An example of this process for a non-standard menu follows. 
Listing #1 is the code that creates the Menu Definition 
Resource and listing 42 shows how to use it. 


(ar listing fragment #1 the resource def program------- ) 
(nust be compiled with the DeskAcc option checked) 
program TheMDEFProc; 


(pascal directive to create a MDEf resource) 
(---» $C type id [attribute] [name] «---) 


($C 'MENU' 256 4 'TheMDEFRes') 
var ( no globals allowed ) 


procedure theMDEFProcedure(...); 


in 
beg code to impliment the Menu Def ) 


) 


begin (no main progrem allowed) 
end. 


(------ listing fragment #2 the program that uses the res-----) 
program UseTheMenu; 


($L TheMDEFProc) (link the file we created above) 
(it includes the menu def we created) 


Two methods can be used to put a handle to your MDEF 
resource in the MenuProc field of the menu. 

(1) In the menu resource, change the menuID field to the 
resource id of your MDEF.  Then,when you call the 
GetMenu function, the Menu Manager will automatically 
read the MDEF resource from the resource file, and place a 
handle to it in the MenuProcField of the menu 

(2) If you create the menu (or window) by any means other 
than reading a resource (by calling NewMenu, for 
instance), you must get a handle to the MDEF by 
executing the following code: 


MyMenuHand := NewMenu( 100, 'menuTitle'); 
myProcHdl := GetResource( 'MDEF ' , 256); 
MyMenuHand**.menuProc := myProcHd!; 


2. By putting the proc in your code and creating a 
handle to it. 

First get a handle to your object, by calling NewMenu or 
GetNewMenu. Then get a handle to the definition routine, 
which may be part of your code, and shove it into the 
MenuProc field of your objects record. An Example of this 
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method follows: 


var 
myMenuHdl : MenuHandle; 


procedure TheMenuProc(...); 
begin 
end; 


myMenuHdI := GetNewMenu(...); 
myMenuHdl^^.menuProc :- NewHandle(0); 
myMenuHd1**.menuProc* := Ptr(éTheMenuProc); 


Things to Come 

All of the definition routines are passed a message which 
tell them what kind of action the are to do. Typical actions 
are Initialize, Draw, Select, Drag, Size, ect. A brief 
introduction to the individual definition routines we will cover 
in the in the next couple of months follow: 

Menu Defintion Procedure 

The menu definition procedure has the following Pascal 

definition: 


procedure MyMenu(message : integer; 
theMenu : MenuHandle; 
ver menuRect : Rect; 
hitPt : Point; 
ver whichItem : Integer); 
The message parameter tells you what kind of action to 
take, it may be one of the following values: 
mDrawMsg 
If the menu definition procedure is passed this value it 
should draw theMenu inside menuRect. 
mChooseMsg 
If the menu definition procedure is passed this value it 
should hilite the item which hitPt is in, unhilite the old 
item, and return the new item in whichltem. 
mSizeMsg 
If the menu definition procedure is passed this value it 
should calculate the width and height of the menu and put 
the results in theMenu^^. width and theMenu™ height 
respectively. 
Window Defintion function 
The window definition function has the following Pascal 
definition: 


function MyWindow(varCode : integer; 
theWindow : WindowPtr; 
message : integer; 
perem : LongInt) 
: LongInt; 


The message parameter tells you what kind of action to 
take, it may be one of the following values: 
wDraw 
If the window definition function is passed this value it 
should draw the window frame. Before doing this, 
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however, the routine should check to see if the window 
frame should show hiliting, if the window is visible, if 
the window has a go-away box, ect. 

wHit 
If the window definition function is passed this value it 
should inspect param, which is the point where the 
mouse was pressed. Then it should check to see if the 
point is in one of the windows regions, such as the 


Fig. 2 A non-standard window definition 


GoAway region, and return the appropriate result. 
wCalcRgns 
If the window definition function is passed this value it 
should calculate the windows current structure and 
content regions and store the results in the window 
record. 
wNew 
If the window definition function is passed this value it 
should perform any extra initialization and allocation it 
may require. 
wDispose 
If the window definition function is passed this value it 
should perform any additional disposal actions which it 
may require. This message "Undo's" whatever was done 
in the wNew routine. 
wGrow 
If the window definition function is passed this value it 
Should draw a grow image of the window to fit the given 
rectangle. This operation is called repeatedly when the 
user drags inside the grow region. 
wDrawGlcon 
If the window definition function is passed this value it 
should draw the size box icon in the window. 
Control Defintion Function 
The control definition function has the following Pascal 
definition: 


function MyControl(varCode : integer; 
theControl : ControlHandle; 
message : integer; 
param : LongInt) 
: LongInt; 


The message parameter tells you what kind of action to 
take, it may be one of the following values: 
drawCntl 

If the control definition function is passed this value it 
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should draw all or part of theControl. 
testCntl 
If the control definition function is passed this value it 
should test where the mouse button was pressed. 
calcCRgns 
If the control definition function is passed this value it 
should calculate the control or its indicators regions. 
initCntl 
If the control definition function is passed this value it 
should do any extra initialization actions it needs to 
perform. 
dispCntl 
If the control definition function is passed this value it 
should take any additional disposal actions. 
posCntl | 
If the control definition function is passed this value it 


should reposition the controls indicator, and update it. 
thumbCntl 


If the control definition function is passed this value it 

should calculate parameters for dragging indicator. 
dragCntl 

If the control definition function is passed this value it 

should drag the control or its indicator. 
autoTrack 

If the control definition function is passed this value it 

should execute the control's action procedure. 

. List Defintion Procedure 

The list definition procedure has the following Pascal 

definition: 


procedure MyList(lmessage : integer; 


lSelect : Boolean; 
]Rect : Rect; 

1Ce1l : Cell; 
lDatae0ffset : integer; 
lDaetaLen : integer; 
lHandle : ListHandle); 


The message parameter tells you what kind of action to 
take, it may be one of the following values: 
linitMsg 
If the list definition procedure is passed this value it 
should do any additional list initialization. 
IDrawMsg 
If the list definition procedure is passed this value it 
should draw the cell. 
IHiliteMsg 
If the list definition procedure is passed this value it 
should invert the cell's highlite state. 
ICloseMsg 
If the list definition procedure is passed this value it 
should take any additional disposal actions. 
A Warning From Apple 
Apple has stated, "For the convienience of the 
applications user, remember to conform to the Macintosh 
User Interface Guidlines as much as possable". I agree totally. 
So don't make a round menu or a window in the shape of a 
Apple. (I've already done them both anyway!) [Wow! How 
about publishing the Apple window? -Ed.] 
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Hello, as promised, we will cover Menu Definition 
Routines this month. What is a Menu Definition Routine? It 
is a procedure that defines a particular type of menu. The 
routine controls the way menus are drawn, and how items 
within it are selected. In general, Menu Definition routines 
define a given menu's appearance and behavior. The standard 
type of Macintosh menu is pre-defined for you and it is stored 
in the system file. You may however, want to define your 
own type of menu. The pattern selection menu in MacDraw 
is a good example of a non-standard menu. 

The menu definition procedure I decided to use for an 
example doesn't create a non-standard menu but it shows 
exactly how the standard menu definition works! The standard 
definition routine was written in 68000 Assembler, by Andy 
Hertzsfield (my Hero) but ours will be written in TML Pascal 
(with the exception of one routine, which couldn't be written 
with Pascal, so I wrote it in 68000 Assembler). There isn't 
any noticeable speed difference between the standard Menu Def 
and our imitation. 


Pattern 


An example of a non-standard Menu 


The Pascal definition and general outline of a Menu 
definition procedure follows: 


procedure MyMenu(message : integer; 
theMenu : MenuHandle; 
var menuRect : Rect; 
hitPt : Point; 
var whichItem : Integer); 
procedure DoDrawMessage(aMenu : MenuHandle; 
aRect : Rect); 
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... (draw the menu in menurect) 


end; 
procedure DoChooseMessage(aMenu : MenuHandle; 
aRect : Rect; 
aPt : Point; 
var altem : Integer); 
begin 
... (see what item aPt is in and select it) 
end; 
procedure DoSizeMessage(aMenu : MenuHandle); 
begin 
... (calculate the width and height of aMenu) 
end; 
begin 
case message of 
mDrawMsg : 
DoDrawMessageCtheMenu, menuRect); 
mChooseMsg : 


DoCooseMessage(theMenu, menuRect, 
hitPt, whichItem); 
mSizeMsg : 
DoSizeMessage( theMenu); 
end; 
end; 


The Parameters 


The message parameter tells type of operation to perform. 
It can be one of the following values: 


mDrawMsg  - Draw the menu. 
mChooseMsg - Choose a item. 
mSizeMsg - Calculate the menu's height & width. 


The 'theMenu' parameter is a MenuHandle to the menu 
we are to perform the action on. 

The 'menuRect is the rectangle in which the menu is in. 
It is in global coordinates. 

The 'hitPt parameter is the point (again, in global 
coordinates) that the mouse was pressed. It is only valid 
during a 'mChooseMsg'. 

The 'whichItem' parameter holds the item number that is 
currently selected. You pass the result of your hit test back to 
the menu manager in this parameter. 


The DoSizeMessage Procedure 

When we are passed the mSizeMsg message, we need to 
calculate the width and height of the menu passed in theMenu 
parameter. The results are returned in the menu records Width 
and Height fields respectively. For a menu which has only 
one size, MacDraw's pattern selection menu, for example, this 
is real easy- just assign the width and height fields their 
constant values. For your example, which has variable widths 
and heights, it is a little harder. 

The way we do this is have a variable that holds the 
cumulative vertical distance and another which holds the 
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greatest horizontal distance. We loop through each item, first 
getting all its attributes (icon, text, cmd key...). Then we add 
the current items height to the cumulative height variable (36 
if it has a icon, 16 otherwise). We must also find the items 
width; this is done by checking for icons, cmd keys, the items 
string width, etc. If this items width is greater than all others 
we have encountered so far, then we update the greatest width 
variable. When we have done this for all items in the menu, 
we return the results in the menu record fields Width and 
Height. 
The DoDrawMessage Procedure 


The DoDrawMessage is called when we receive a 
mDrawMsg from the menu manager. In response to this, we 
draw the menu items in theRect. When we are called, the 
current port will be the WindowMgrPort and the boarder 
around the menu will already be drawn. Again, we just go 
through a loop, looking at every item. If the item has an icon, 
we draw it and bump the location of where the text will go 
down half the size of the icon. We draw the markChar, if any. 
Then we draw the items text, and finally, the items keyboard 
equivalent, if any. 


The DoChooseMessage Procedure 


When we receive a mChooseMsg we call the 
DoChooseMessage and pass it the following parameters. The 
'aPt' parameter is the mouse location that we need to check 
for. The 'whichItem' parameter is the item number of the last 
item that was choosen from this menu (initially 0). First we 
check to see if the point is in the menus rect, if not, we return 
0. Otherwise, we see if the point is in an enabled item, if not, 
we return 0. If it was in an enabled item, we need to unhilite 
the old item (unless they are the same), hilite the new item 
(again, unless they are the same), and return the item it was 
in. 

Getting the Menu Manager to Use our Def 


Now that we have our definition routine defined, how do 
we get the Menu Manager to use our definition routine instead 
of the standard one (even thought they act the same)? One 
method of doing this follows: 


1. Get the handle to the menu by calling NewMenu or 
GetNewMenu. 

2. Put a new handle in the menuProc field of the menu record. 

3. Make that point to the address of our MenuDefRoutine. 


myMenuHdl := GetNewMenuC...2; 
myMenuHdl^^.menuProc := NewHandle(0); 
nyMenuHdl^^.menuProc^ := PtrC@TheMenuProc); 


Other Points of Interest 


The assembly routine we use in this example simply 
returns the keyboard equivalent of a menu item. Since there is 
no standard trap to do this, and it can't be done with Pascal, no- 
wait a minuite...it can be done with Pascal. But it is a lot 
easier with assembly, so there! Anyway, it simply walks 
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Fig. 1 Our own standard menu proc routine 


through the menu record until it finds 'theItem', and it gets its 
keyboard equivalent and returns it. It's Pascal declaration is : 


procedure GetItemKeyCtheMenu : MenuHandle; 
theItem : Integer; 
var theChar : Char); external; 


This is only one type of menu def, the number of 
possible menu definition routines that can be made are as big 
as your imagination, and, of course, available memory. For 
example, in addition to the MacDraw type MDEF I have done 
for the TML Examples Disks, I have done a Hierarchical 
Menu Definition routine. The way it works is this: to define 
a sub-menu in a menu, you simply add the string IXXX' to 
the item you want to have the sub-menu. The XXX is the 
resource id of the menu you want to be the sub menu of the 
item. So, when I am supposed to draw the menu or calculate 
the menu's size, I strip out the 'IXXX' string. Where it gets 
fancy is when you get the choose message, and you move 
onto an item that has a submenu ((IXXX' in its string). When 
this happens, I call a Pascal version of Mike Shuster's 
PopUpSelect routine [published in MacTutor December 1985 
issue and available as a back issue for $4] for the menu with 
the res ID XXX. If the same conditions occur in the 
PopUpSelect routine, which calls the Definition Routine, I 
call it again. Can you say RECURSION ? I knew you could. 

A good use for this type of Menu Def is a Character 
Menu, its items are Font, Size, and Style. When you move 
the mouse over one of these items, a list of fonts, a list of 
available sizes, or a list of styles appear in the sub menu. The 
advantage of this is that it only took one place in the menu 
bar to implement 3 separate menus. 


Next Month... 


Next month we will cover the wonderful world 
of Window Definition Routines. We will go through an 
example that shows how the standard window definition 
routine works. I would suggest reading the Window Manager 
section of Inside Macintosh, especially the section on 
"Defining Your Own Windows". If you have any 
questions/suggestions or other form of abuse, drop me a line 
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Fig. 2 Next month...Windows! 


in care of MacTutor. Or better yet, buy the TML Examples 
Disks, there is 3 MDEF Examples in them. Its been real... 


Pascal Source Code 


CEPPEEECECEC CCC eC CSC Cee eee Lee eee erEe eet Pt PT Tt i 


tt 
tt RegMDEF .Pas 

tt 

8 (Regular Menu Definition Routine Exemple) 
# ( just like apples, except in Pascal ) 

a 

"a This program was written by Darry! Lovato. 

# Copyright (c) 1986 by TML Systems. 

# 


AONNRRNNNNNNANNNNRNNNNNNNNNNRRNNNNHBENNHHRRRNNHHN ) 
program RegMDEF ; 
E Compiler Directives --------------------------- ) 


($B+ ) ( Tell the linker to set the bundle bit) 
($T APPL RMF  ) type to App] and creator to RMDF) 
($I MemTypes. ipas) ( Include the Memory Declarations) 
($I QuickDraw. ipas) ( Include QuickDraw Declarations) 
($I OSIntf.ipas ) ( Include the OS Declarations) 

($I ToolIntf . ipas )( Include the Toolbox Declarations) 
($L RegMDEFRsrc) ( Tell the linker to link the resources) 
($U RegMDEFGlue) ( link our assembly code in too...) 


i roessacuE IEEE Global Constants ---------------------------- ) 
const 
appleMenu = 300; ( Resource ID of the Apple menu) 
fileMenu = 301; { Resource ID of the File menu) 
editMenu = 302; { Resource ID of the Edit menu} 


beginMenu = 300; ( Res ID of first menu in menu bar) 
endMenu = 302; ( Res ID of last menu in menu bar} 
RegMenu = 500; ( Res ID of our regular menu) 


(------------ Global Variables ------------------------------ ) 


var 
( The menus in menu ber) 
myMenus : arraylbeginMenu. .endMenu] of MenuHandle; 
Finished : Boolean; ( Set to true when were done) 
screenPort : GrafPtr; ( the window mngr port) 
MyRegMenu : MenuHandle; ( my regular menu handle) 


ERREEN Assembly Procedures ---------------------------- ) 
procedure GetItemKeyCtheMenu : MenuHandle; 
theItem : Integer; 
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var theChar : Char); external; 
(---------- ChkOnOffItem procedure -------------------------- ) 


procedure ChkOnOffItem(MenuHdT:MenuHandle; item, first, 
last: Integer); 


var 
i: integer; 
begin 
for i := first to last do 
begin 
if item = i then 
CheckItemC(MenuHdl, i, true) (check it on in menu) 
else 
CheckItem(MenuHdl, i, false); (check it off in menu) 
end; 
end; 
(------------ MenuDef Procedure ----------------------------- ) 
procedure MyMenuDef(message : Integer; ( what do we do?) 
theMenu : MenuHandle; ( what menu ?) 


( in what rect?) 
( where's mouse?) 
( what item is it?) 


ver menuRect : Rect; 
hitPt : Point; 

var whichItem : Integer); 
(Feii Semi-global constants ---------------------------- ) 


const 
MBarHeight = 290; 


procedure DimRect(theRect : Rect); 
begin 
PenPat(gray); 
PenMode(patBic); 
PaintRect( theRect); 
PenNormal; 
end; 


function GetItemsRect(myMenu : MenuHandle; 
myRect : Rect; 
theItem : Integer) : Rect; 
var 
Index : Integer; 
currentRect : Rect; 
itemIcon : Byte; 
begin 
currentRect .bottom:=myRect. top; (initialize current rect) 
currentRect.left := myRect. left; 
currentRect.right := myRect.right; 
for index := 1 to theItem do 
begin 
GetItemIcon(myMenu, index, itemIcon); 


currentRect.top := currentRect.bottom; ( update rect ) 
if itemIcon o Ø then 
currentRect.bottom := currentRect.top + 36 


else 
currentRect.bottom := currentRect.top + 16; 
end; 
GetItemsRect := currentRect; ( return result) 
end; 
(Sesser ees DoDrawMessage Procedure ----------------------- ) 
procedure DoDrawMessage (myMenu : MenuHandle ; nyRect :Rect); 
const 
MBarHeight = 29; 
var 
currentItem : Integer; 


currentRect : Rect; 
itemString : str255; 
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itemIcon : Byte; 
itemMark : Char; 
itemStyle : Style; 
itemKey : Char; 
thePoint : Point; 
theIcon : Handle; 
iconRect : Rect; 
NewVert : Integer; 


begin 
currentRect .bottom:=myRect. top; (initialize current rect) 
currentRect. left := myRect. left; 
currentRect.right := myRect.right; 
for currentItem: 1 to CountMItems(myMenu) do(all items) 
begin 
GetI tem(myMenu, currentItem, itemString); ( get info ) 
GetItemIconCmyMenu, currentI tem, itemIcon); 
GetI temMark (myMenu, current! tem, itemMark); 
GetI temStyleCmyMenu, currentI tem, itemStyle); 
GetI temKeyCmyMenu, current! tem, itemKey); 


currentRect.top := currentRect.bottom; ( update rect ) 
if itemIcon € Ø then 

currentRect.bottom := currentRect.top + 36 
else 

currentRect.bottom := currentRect.top + 16; 


if itemString = '-' then ( special case '-' item) 
begin 
PenPat (Gray); 
moveToCcurrentRect.left,currentRect.top + 8); 
LineCcurrentRect .r ight, 2); 
PenPat(Black); 
end 
else ( draw the other item stuff) 
begin (get baseline) 
NewVert := (CcurrentRect.bottom - currentRect. top) 


NewVert := currentRect. top + 4 + Newert; 
MoveToCcurrentRect. left + 2,newVert); 


if itemMark © Chr(2) then 
DrawChar Ci temMark ); 


if itemIcon © Ø then ( drew the icon) 
begin 
iconRect.top := currentRect.top + 2; 
iconRect bottom := iconRect.top + 32; 
iconRect. left := currentRect.left + 13; 
iconRect.right := iconRect.left + 32; 
theIcon := GetIcon(256 + itemIcon); 
PlotIconCiconRect, theIcon); 
GetPenCthePoint); 
MoveToCcurrentRect.left + 47, thePoint.v); 
end 
else ( otherwise, just move over a bit) 
begin 
GetPenCthePoint); 


MoveToCcurrentRect.left + 13, thePoint.v); 
end; 


TextFaceCitemStyle); 
DrewStringCitemString); 
TextFace({]); 


if itemKey <> Chr(0) then ( draw key equiv} 
begin 
GetPenCthePoint); 
MoveToCcurrentRect.right - 24, thePoint.v); 
DrawChar(Chr($11)); ( draw cmd char symbol) 
DrewCharCitemKey2); ( and the cmd key) 
end; 


if (BitAndCmyMenu^* .enaebleFlags, 1) = 0) 


then (disabled!) 


DimRectCcurrentRect); 
if CBitAnd(BitShif t¢ 
myMenu** .enableF lags, -currentI tem), 1) = Ø) then 


DimRectCcurrentRect); 
end; ( of if itemString = '-' then..else..} 


end; 
end; ( of DoDrewMessage) 


function DoChooseMessage(myMenu : MenuHandle; 


myRect : Rect; 
myPoint : Point; 
oldItem : Integer) : Integer; 
var 
theItem : Integer; 
ItemsRect : Rect; 


begin 
if PtInRectCmyPoint,myRect) then 
begin 
theItem := 1; 
repeat 


ItemsRect := GetItemsRect(myMenu, myRect, theItem); 
theItem := theItem + 1; 


until PtInRect(nyPoint, itemsRect); 
theItem := theItem - 1; ( undo last increment) 


if (BitAnd(myMenu*^*^ .enableFlags, 1) = Ø) or 
(BitAnd(BitShift( 
myMenu^^ .enableF lags,-theItem), 1) = Ø) then 
begin 
theItem := Ø; 
end; 


if theItem <> oldItem then (de-select old, select new) 
begin 
if oldIitem €» Ø then ( deselect old) 
Inver tRect(GetI temsRect( 
myMenu, myRect,olditem)); 
if theltem <> Ø then 
PAE here wwe teene nec MUNERA myRect, theI tem)); 
end; 
DoChooseMessage := theltem; ( return result) 
end 
else ( it was not in our menu) 
begin 
if oldItem € Ø then ( we need to de-select old item) 
InvertRect(GetItemsRect(myMenu, myRect,oldItem)); 


DoChooseMessage := 8; ( return result) 
end; 


procedure DoSizeMessage(var myMenu : MenuHandle); 


ver 
MaxWidth : integer; { keep track of the maximum width) 
TotalHeight : integer; { keep track of the total height) 
currentItem : integer; { the menu item we are looking at) 
itemString : Str255; ( text of the curren menu item) 
itemIcon : Byte; ( resource id of the menu items icon) 
itemMark : char;  ( the items mark} 
itemStyle : Style; ( the items character style) 
itemKey : Char; ( the keyboard equiv) 
tempWidth : Integer; ( the current items width) 


begin 

MaxWidth := Ø; ( initailize width) 

TotalHeight := 0; ( initialize height) 

for currentItem := 1 to CountMItems(myMenu) do 

begin 
GetI tem(myMenu, currentItem, itemString); ( get text) 
GetI temIcon(myMenu,currentI tem, itemIcon); (get icon) 
GetI temMark (myMenu, currentI tem, itemMark); ( cher) 
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GetI temStyleCmyMenu, currentI tem, itemStyle); ( style) 
GetItemKeyCmyMenu, currentI tem, itemKey); ( get key) 


tempWidth := 13; ( indent a bit) 
if itemIcon € Ø then 

tempWidth := tempWidth + 35; ( make room for icon) 
TextFaceCitemStyle); ( set to items style) 
tempWidth := tempWidth + StringWidthCitemString) + 4; 
TextFace([]); (return to normal) 
if itemKey <> ChrC20) then 

tempWidth := tempWidth + 30; 


if tempWidth » MaxWidth then 
MaxWidth := tempWidth; 

if itemKey © chr(0) then 
tempWidth := tempWidth + 20; 


if itemIcon <> Ø then 
TotalHeight := totalHeight + 36 ( add lots of space) 
else 
TotalHeight : 
end; 
with myMenu** do 
begin 
menuWidth :- MaxWidth; ( save result in menu record) 


totalHeight *16; (add enough for text) 


menuHeight :- TotalHeight; ( ditto...) 
end; 
end; 
(esir Case on message and call procedure -------- ) 
begin 
case message of 
mSizeMsg : 
begin 
DoS izeMessage( theMenu) ; 
end; 
mDrawMsg : 
begin 
DoDrawMessage( theMenu, menuRect); 
end; 
mChooseMsg : 
begin 
whichItem := DoChooseMessage( 
theMenu, menuRect ,hitPt, whichI tem); 
end; 
end; 
end; 
(--------- process the menu selection ------------------- ) 


procedure ProcessMenu(CodeWord : LongInt); 


var 
menuNum : Integer; ( Res ID of the menu Selected) 
itemNum : Integer;( The item number selected) 
nameHolder : str255; ( the name of the desk acc.) 


dummy : Integer; ( just a dummy) 
AboutRecord : DialogRecord; ( the actual object) 
AboutDlog : DialogPtr; ( a pointer to my dialog) 


begin 
menuNum :- HiWord(CodeWord); — ( get the menu number) 
itemNum := LoWord(CodeWord); — ( get the item number) 
if itemNum > Ø then ( ok to hendle the menu?) 
begin 
cese MenuNum of 
eppleMenu : 
begin 


case ItemNum of 
1: 
begin 


AboutDlog := GetNewDialog( 
3000 , @AboutRecord, Pointer(-1)); 
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Moda lDialog(nil, dummy); 
CloseDialogCAboutD10g); 
end; 
2:begin 
end; 
otherwise 
begin 
GetItemCmyMenus [eppleMenu], 
ItemNum, NameHolder); 
dummy := OpenDeskAcc(NameHolder); 
end; 
end; 
end; 
fileMenu : 
begin 
Finished := true; 
end; 
editMenu : 
begin 
if not SystemEditCItemNum - 1) then 
begin 
(we dont support any other editing) 
end; 
end; 
RegMenu : 
begin 
if ItemNum o Ø then 
begin 
if itemNum > 3 then 
ChkOnOffItemCMgRegMenu, ItemNum, 4, 9); 


end; 
end; 
end; ( of case menuNum of) 
end; ( of if CodeWord...) 
HiliteMenuC0); 
end; ( of process menu) 
aes Main Event loop -------------------------------) 


procedure MainEventLoop; 


type 
trickType = packed record(to get around pascal's typing) 
case boolean of 


true : 
CI : LongInt); 
false : 
(chr3, chr2, chr1, chrØ : Char); 
end; 
var 
Event : EventRecord; ( Filled by Get next event) 
windowLoc : integer; ( the mouse location} 
mouseLoc : point; ( the area it was in ) 
theWindow : WindowPtr; ( Dummy, have no windows) 
trickVar : trickType; ( because of pascal's typing) 
CharCode : Cher;  ( for command keys) 
begin 
repeat ( do this until we selected quit) 


SystemTask; ( Take care of desk accessories) 
if GetNextEventCeveryEvent,Event) then 


begin 
cese event.what of —( case out on the event type) 
mouseDown : ( we had a mouse-down event ) 
begin 


mouseloc := Event.where; ( wheres the mouse) 
windowLoc := FindWindow(mouseLoc, 
theWindow); 
case windowLoc of ( now case on the location) 
inMenuBar : 
ProcessMenu(MenuSe lect (MouseLoc)); 
inSysWindow: 
SystemClick(Event, theWindow); (In desk acc) 
end; 
end; 
keyDown,AutoKey : ( we had the user hit a key) 
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begin 
trickVar.I := Event.Message; { fill the longWord) 
CharCode :=trickVar.chr@; (and pull off low-byte) 
if BitAndCEvent.modifiers,CmdKey) = CmdKey then 
ProcessMenuCMenuKeyCCharCode )); 


end; 
end; ( of case event.what...) 
end; ( end of if Get Next event) 
until(Finished); ( end of repeat statement) 
end; ( of main event loop) 
cana cea SetUp Everything: *5---eeeee eoe nene ceo ene ) 


procedure SetUpThings; 


type 
ProcHdl = ^ProcPtr; 
var 
index : integer; ( used in a for loop ) 
begin 
for index := beginMenu to endMenu do 
begin 
myMenus[ index] := GetMenuCindex2; ( Get next menu) 
end; 


AddResMenu(myMenus [app leMenu), ' DRVR' ); 
for index := beginMenu to endMenu do 
InsertMenuCmyMenus[ index],@);{ Insert the menu ) 


( #xexnxnxex here is the non-standard menu*txüxmknminxmxg ) 
MyRegMenu := GetMenu(580); ( make a new Menu) 
MyRegMenu**.menuProc := NewHandle(@); 
MyRegMenu^^.menuProc^ := PtrC@MyMenuDef ); 


InsertmenuCMgRegMenu,2); ( and add it to the menu list) 
CalcMenuSizeCMgRegMenu?; ( and calculate its size) 


DrawMenuBar ; ( Now draw the menu bar ) 
ChkOnOff ItemCMyRegMenu, 4, 4, 92; (check item in menu) 
end; 
(en Initialize Everything ---------------------------- ) 
procedure InitThings; 
begin 
InitGraf CGthePor t); ( create grafPort for screen) 
MoreMasters; ( create bunch of master Ptr's) 
MoreMasters; ( wont need to worry about) 
MoreMasters; ( heap fragmentation later!) 
MaxApp Zone; ( make sure we have lots!) 
InitFonts; ( Startup the Font manager} 
InitWindows; ( Stertup the Window manager) 
InitMenus; ( Startup the Menu manager) 
TEInit; ( initialize text edit ) 
InitDialogs(nil); ( initialize dialogs  ) 
InitCursor; ( make the cursor an arrow) 
end; 
(-----7-7--7--7-- Main Program Seg ------------------------------ ) 
begin 
InitThings; 
SetUpThings; 
Finished := false; 
MainEventLoop; 
end. 


Assembly Source Code 


QPIHHBHHHHHHEHEHHEHHHHHHEHHHHHHHHHHHHHEHHHHHHHHHHH 
8 
" 


;® procedure GetItemKegCtheMenu : MenuHandle; 
Qs theItem : Integer; 

L var theChar : Char); 

I 

J 
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tt 

8 This assembly proc returns the current command key 
# which is assigned to theltem. 
# 
8 


unmtummuimniuiimiuiumiminiiuimimniuiuiniiniii tiit Hi UH NN 


; nenuinfo data structure 


menuID equ 8 ; unique id for menu bar [word] 


menuWidth equ 2 ; menu Width (word) 

menuHe ight equ 4 ; menu Height [word] 

menuDef Handle equ 6 ; menu definition proc [handle] 
menuEnable equ $A ; enable flgs, one bit/item [long] 
menuData equ $E ; menu item string [string] 
menuBlkSize equ $E ; menu block plus dataString 


; menu string data structure 


itemIcon equ @ ; icon byte 

itemCmd equ 1 ; command key byte 
itemMark equ 2 ; checkmark character byte 
itemStyle equ 3 ; style byte 


.Trep _CountMI tems $A958 ; trap word 


xdef GetItemKey 


nn MM a 8] 0 — a secte nee eee ex mee 
GetItemKey 
link  A6,"g ; create new stack frame 
movem.1] A®-A4/D8-D3,-(SP) ; save registers 
"AA secu Pop (Or ane ters: Sheer eiee eee eee 
clr.1 D2 ; make sure it is empty 
cir.] Dl ; ditto... 
clr.1 DØ ; ditto... 
clr.w -(SP) ; make room for result 
move. | 14CA6),-CSP); push MenuHandle 
-CountMItems ; how many are in this menu? 
move.w (SP )+,D03 ; pop result 


move. 1 14(€A6),A4 
move .w 12(A6),D1 
movea. 18C(A6), A3 


; fetch the menu handle 
; fetch the item number 
; fetch ptr to the char Ptr(word) 


cmp.w D1,D3 ; num of Menu Items « theItem? 
blt  BadItem ; yep, exit 


move .1(A42,A4 ; get menu ptr 

lea menuDataCA4),A4 ; now A4 points to menu title 
move .b (A42,D2 ; get length of menu title 

add.b 81,D2 ; Skip length byte 


; (A4,D2) now points tothe first menu items titleClength byte) 


nextItem 
Sub.b #1,D1 ; decrement count 
beq GotItem ; if Ø, return its cmd char 
move .bCA4,D2),D8  ; get length of the title 
add D@,D2 ; and skip it 
add 85,D2 ; skipe item attrib& length byte 
bra nextItem ; and look at the next item 
icu E ES eee Got the Item 2 ose sa sessssesserrsare 
GotI tem 
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move .bCA4,D2),D8 ; get length of title 
add D0,D2 ; and skip it 
add #1,D2 ; Skip length byte, too... 
clr.w DØ ; make sure its empty 
move.b itemCmd(A4,D2),D0 

; get the key equivalent 


move .wDO,CA3) ; and return it 


bra Exit , and exit 
Ra No Item Found, sscseecsecesessceeoeco e cnrene 
BadItem 

clr.w (A3) ; return no cmd char and exit 
jo EE Clean Up & Exit e-eseeesecoeeceeecroe n 
Exit 


movem. 1 CSP )+,A@-A4/D8-D3 ; restore registers 


unlk A6 ; restore stack frame 
movea. | CSP )+, Ad ; save return address 
adda.1#18,SP; clean up stack 
jmp (AQ) jo. and return 
Link File For TML Pascal 
IPAS$Xfer 
/Globals -4 
RegMDEF 
Pascal System:PAS$Library 
OSTraps 
ToolTraps 
Pascal System:RegMDEFGlue 
/Resources 
Pascal System:RegMDEFRsrc 
/Bundle 


lure "APPL' 'RMDF' 


Resource File For RMaker 
* 
* Resource listing: "RegMDEFRsrc". 
x 


RegMDEFRsrc 


TYPE RMDF=STR 
A) 
Window Definition Procedure 


TYPE BNDL 
, 128 

RMDF Ø 

ICN! 

0 128 1 129 

FREF 

Ø 128 


Type DLOG 
,9000 (4) 

New Dialog 

96 74 312 444 

Visible GoAway 

1 

9 

3000 


Type DITL 
,9000 


x — ] 
BtnItem Enabled 
200 239 237 324 
Okay 
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* 2 

StatText Disabled 

16 83 34 284 

MacLanguage Series™ Pascal 


x 3 

StatText Disabled 

34 69 58 293 

Advanced Programming Examples 


* 4 

StatText Disabled 

61 52 77 307 

- Standard Menu Definition Example - 


* 5 

StatText Disabled 

98 6 139 368 

Written by Darryl Lovato. ++ 

\ODSpecial thanks to Robert Ulrich. ++ 
\@DCopyright € 1986 by TML Systems. ++ 
All rights reserved. 


* 6 

StatText Disabled 

147 7 180 364 

Complete source code for this example ++ 
Cand others) is available from: 


x 7 

StatText Disabled 

183 68 258 198 

TML Systems, Inc. ++ 

\ØDP.0. Box 361626 ++ 

\@DMelbourne, F1 32936\00(385) 242-1873 


x 8 

IconI tem Enabled 
14 21 46 53 

3000 


Type MENU 

„DOO (4) 
Junk 
Icon Item^1 
(Disabled Item 
(- 
keyboard Equiv Item/K 
Shadowed Item«S 
Outlined Item<0 
Underlined Item«U 
Italic Item<I 
Bold Item«B 


, 308 (4) 
M4 
About Regular MDEF... 
(- 


,9801 (4) 
File 
Quit/Q 


,9302 (4) 

Edit 

Undo/Z 

(- 

Cut /X 

Copy/C 
Paste/V 

Clear 


Type ICON = GNRL 
,251 (4) 
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FFTFFFFF 
B 16AAAAB 
ET555555 
247EAAAB 
240 15555 
247CAAAB 
24827F55 
250 10 148 
2539 1C55 
2521633F 
E7208080 
8 12088E7 
FF27 1465 
01392255 
F9011455 
E482888D 
E47CB0A5 
9A0063A 1 
99FE 1031 
E6678 129 
E66679E7 
9999900 
99999BFF 
E6666667 
E6666667 
99999999 
99999999 
E6666667 
E6666667 
99999999 
99999999 
FFFFFFFF 


,3000 (36) 


3FFFFFFC 
40000002 
BICIFFCI 
822 10041 
FESFOO7F 
92290049 
9 1COFFC9 
90080009 
9008 1C09 
90C82209 
9 127E3F9 
9F302201 
9 1281C01 
90C8000 1 
9008 !F01 
9008608 1 
93C 1804 1 
94223020 
9C2FC8 10 
94247F OF 
93C23007 
900 10007 
90008007 
90006001 
93CO IFE7 
942000 IF 
OC3FEGO7 
84200008 
83C00008 
8000000 1 
40000002 
SFFFFFFC 
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Type ICN® = GNRL 
128 


2 


00000000 
TFFFFFFE 
4TE00002 
4TE00002 
TFFFFFFE 
5400 1556 
6DCØ 1AAA 
55DF9556 
6DCØ 1AAA 
5400 1556 
6DCÓ 1AAA 
555ED556 
6DCØ 1AAA 
5400 1556 
6EAABAAA 
5400 1556 
6FFFFAAA 
56073556 
6FFFFAAA 
5400 1556 
6DEEDAAA 
5400 1556 
6DF8 1AAA 
5400 1556 
6FFFFAAA 
55555556 
6AAAAAAA 
55555556 
GAAAAAAA 
55555556 
TFFFFFFE 
00000000 
x 

FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
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Joel West 
Resource Roundup 4 Contributing Editor 
Be a Keyboard Sleuth! Wis E Vista, CA 


See the world through a keyboard 


In the last installment of Resource Roundup, the general 
concepts of resources were introduced, and passing mention 
was made of their role in Apple's international marketing. 

Among the stated justfications for the resource concept 
was to make it easier to support software in multiple 
countries. Most software previously had strings embedded in 
the software, such as 


writeC'File ', filenam, 
' cannot be opened. ') 


which have to be completely rewritten by a programmer 
(using the proprietary source code) for any foreign market. 
However, with resources available, a properly designed 
Macintosh application can be translated by just about anybody 
using REdit. (I don't know Steve Jobs personally, so I can't 
say if this was a major factor, or merely an after-the-fact 
rationalization for the design.) 

If you've ever studied a foreign language, you've 
probably come to the shocking realization that not all of the 
Indo-European languages content themselves with the letters A- 
Z and standard punctuation. I can certainly recall struggling in 
high school Spanish trying to approximate the ; key with a 
typewriter (the ¿ wasn't even worth trying) or to come up with 
the 8 in German. 

If you've concluded by this introduction that resources are 
used on the Macintosh to support foreign keyboards, you're 
right. But these resources are also used to support the 
differences between the Macintosh and the Macintosh Plus 
keyboards, as well as implementing basic keyboard functions. 
There are also some important electronic and mechanical 
differences between the various keyboards. 


Smart, but not smart enough 


If you ask Apple how to read input from the keyboard, 
you'll get the response that you shouldn't use anything other 
than the ASCII value. Apple has gone to great lengths to 
make various keyboards and nationalities behave similarly. 

However, the return values from GetNextEvent (and 
other less documented interfaces) do include the actual key 
number that is down. You can use this value to support key 
combinations that are not defined by Apple — as long as you 
are aware of keyboard differences. 

There are a number of reasons why you might need to go 
to these lower levels. My interest in keyboards was prompted 
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: The keyboard type is 11, which is a Mac Plus keyboard. 
B This is US, Canadian or down under. 


B Type keys, or click mouse to quit. 
B Key *1 is s (ascii 115). 

BH Key *0, shifted is A (ascii 65). 

Bl Key *50 with Option, shifted is 4 (ascii 473). 
Bl Key *42 with Option is « (ascii 199). 

H Key *33 with Option, shifted is " (ascii 467). 


Output of the Keyboard Sleuth! 


by the terminal program I've been working on in my spare 
time (at the rate I'm going, it should be ready in 1993). 

A number of otherwise good Macintosh programs have 
tried to reach this low level and failed. My ears first picked up 
when I heard a number of terminal emulation programs don't 
work with non-US keyboards, or with the Mac Plus. The 
problem hasn't even escaped Apple; an early version of their 
Smalltalk-80 is one such program, as we'll see later. 

But there are ways to look at lower levels that are 
compatible with all current systems and should be compatible 
with all future systems. This article tells how you can take 
complete control over the keyboard without sacrificing 
portability. It describes the various un- and semi-documented 
resources associated with keyboards, including the Macintosh 
Plus and those sold outside the US. 

This article concludes with “Keyboard Sleuth”, a 
program example that analyzes and reports what keyboard 
you're using, and which keys you are pressing. The program 
was written in 'Rascal', a Pascal type language from Reed 
College. This language is a combination Pascal, Basic and 
Assembly. It has a very nice shell that makes Mac 
programming fast and easy because it allows you more 
flexibility for dealing with the various toolbox data structures 
than the traditionally strongly typed Pascal. This makes it 
more suited to "quicky" programs where the Mac interface is 
secondary to the programming problem. (The distributor for 
Rascal is given at the end of this article.) The complete Rascal 
version is available on the source code disk for this issue. It 
Should be fairly easy to translate the program into TML 
Pascal, and in fact, our Editor took me up on that challenge 
and did just that! Since many of MacTutor's readers probably 
have not heard of Rascal, we are publishing his TML version 
of the program with this article (see Sleuth, Part II in the next 
article). 
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Install keyboard mapping 
] Install keypad mapping 


Figure1:Keyboard-relatedresources and global 


Keyboard Properties 


The best place to start on keyboard input is the "Toolbox 
Event Manager" chapter of Inside Macintosh, if you haven't 
read it already. There's also a brief discussion in the 
"Macintosh Hardware" chapter, but ignore the key numbers 
shown in Figure 9 of that chapter. My interest is software, 
not hardware, so I'll focus on the former in this article. 

For many purposes, the keyboard resembles a standard 
teletype (TTY) input. When you type on the keyboard, a 
series of ASCII characters are available for you. 

If you want to dig deeper (and if you didn't, you wouldn't 
subscribe to MacTutor), there are a number of differences from 
a glass TTY: 

e Extended characters. Character values 0 to 127 are 
defined by the ASCII standard. For the Lisa and Macintosh, 
Apple has added a number of characters (128 to 216, thus far) 
to support foreign languages and typographic symbols. I'll 
refer to these as extended ASCII characters. For simplicity's 
sake, I'll use ASCII to refer to any code in the range 0 to 
216, and standard ASCII for those in the range 0 to 127. 

e Key codes. In addition to the ASCII numeric value, the 
actual key number is available. For each keyboard and 
nationality, Apple defines a standard mapping of modifiers and 
key codes to ASCII characters, but for some purposes (e.g., a 
terminal emulator) you may wish to use a different mapping. 

e Modifier keys. The movement of certain keys is not 
normally available to your program. Instead, these keys 
modify the values returned by other, primary keys. These 
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FKEY 0-9 Function key subroutines 

INTL 0-1 (includes nation code) 

CFIG 0 Enable/disable keyboard switching 
ESCK 256 Keycodes and ASCII for keyboard 


Loc Type Usage 
KbdType $21E BYTE Keyboard series 
ScrDmpEnb $2F8 BOOLEAN Function keys enabled 
KbdVars $216 LONGINT Keyboard variables 
KeylTrans $29E POINTER Keyboard mapping vector 
Key2Trans $2A2 POINTER Keypad mapping vector 
KeyMap $174 BYTE[8] Keyboard bit mask 
KeypadMap $17C BYTE[4] Keypad bit mask 


KeyThresh $18E INTEGER Key repeat delay 
KeyRepThresh$190 INTEGER Key repeat speed 
$206 INTEGER  Encoded delay & speed 


modifier keys are the Option, Command (), 
Shift and Caps Lock. A key code and a particular 
modifer pattern will (usually) determine the ASCII 
value your program sees. 

e Function Keys. Apple has reserved certain 
special key combinations to invoke general-utility 
memory resident programs. These all take the 
form of Command-Shift-digit, of which only four 
are currently assigned. You may wish to disable 
these keys for some purposes. For example, cmd- 
shift-3 will capture the screen and save it to disk in 
a paint document. These are known as 'FKEYS' or 
function keys. You can create and install your own 
function key routines in the system file in a 
manner similar to writing desk accessories. 

* "Dead" keys. In most cases, the accented 
letters used in French, Spanish, German and Italian 
are produced by first typing the accent, then typing 
the letter. Your program won't normally see the 
first key; instead, the ASCII value of the two-key 
combination is returned. The first accent key is 
considered “dead” because it doesn't return a 
separate ASCII value or key code. 

* Different Keyboards. The Mac 128/512 and 
the Mac Plus have slightly different keyboard 
configurations. In addition, Apple has defined a 
whole family of keyboards for various countries 
and languages. 

The resources and global variables used to 


implement these properties are listed in Figure 1. 


Character Set 


The standard ASCII/ISO character set defines 95 printable 
characters (including space), which are directly supported by 
the Mac. There are also nine non-printing characters which 
can be typed, as shown with their corresponding hex codes in 
Figure 2. Backspace, Tab, and Return have meanings similar 
to their accepted ASCII usages, while Apple has adopted 
arbitrary ASCII values for the other six keys. 

If you are echoing input characters to the screen, you will 
have to interpret these control characters yourself. Although 
TextEdit understands the Retum key, in general, these keys 
won't produce any meaningful display when using standard 
output routines, such as DrawSt ring or TEUpdate. 

Additionally, there are the 89 extended ASCII characters, 
as shown in Figure 3. A few support mathematical and word 
processing symbols, such as the copyright (©) and paragraph 
(1) symbols. 

However, most of these are used to support foreign 
languages and typography. A number of languages have 
extended alphabets. These include accented letters (such as á, 
à, â, 4, 4, 4), combinations (æ, ce) and as well as characters 
that do not have English equivalents (B). 

In addition, each language has its own typographic 
customs. In Spanish, exclamatories and interrogatories require 
a leading punction mark, as in 
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ASCII Key ASCII Key 
$03 Enter $1C-4«— 


$08 Backspace $1D — 


$09 Tab 


Figure 2: Non-printing keys 


(Que? ;Hola! 
The German language prints quotations as 
«Deises ist ein Zitat.» 


Ironically, the extended set also includes American style 
quotation marks, as in 


“This is a quotation.” 


since the quote mark (") is strictly a typewriter convenience 
that does not extended to publishing. 

All of the ASCII values in the range 32 to 216 (except 
for non-printing standard ASCII value 127, DEL) have 
corresponding characters in at least one font. (The various 
font-related resources will be discussed in depth in a future 
article.) 


Keyboard Events 


When a key is pressed, it generates a keyboard event. 
Normally, you will only receive a keyboard event when the 
key goes down, with the GetNext Event function returning 
the EventRecord.what field set to keyDown. Unless 
you specifically enable ke yDown events, such as with 


SetEventMask (everyEvent) 


GetNextEvent will not return keyUp events. 

You will, however, get autoKey events by default. 
These are generated by the system after the key has been down 
for a specified delay, and are repeated automatically. 

If the event mask you pass to GetNextEvent includes 
keyDownMask, it should also include autoKeyMask. If 
not, the consequences are hilarious, as I discovered in writing a 
desk accessory in which I decided not to bother with the 
repeating key case. The first letter goes to your program, and 
any subsequent letter will go to some other program or desk 
accessory. 

The delay and repeat rate can be changed by the user with 
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the “Control Panel” desk accessory, and are stored in global 
variables KeyThresh and KeyRepThresh, respectively, in 
units of ticks (1/60 of a second). 

The values set by the user are also saved in the non- 
volatile parameter RAM,which are then used to initialize 
KeyThresh and KeyRepThresh. These permanent values 
can be accessed by the following fragment: 


CONST 
eKeyRate = 8; 
eKeyThresh = 12; 

VAR 
sysperm: SysParmType; 
num: LongInt; 


BEGIN 
sysparm := GetSysPPtr; 
num := ORD4Csysparm^ .kbdPr int); 
rate := BitAnd(BitShif tCnum, eKeyRate), 
ORD4C 1522*2; 
thresh := BitAnd(BitShif tCnum, 
aKeyThresh), O0RD4C152)2*4; 


(The value sysparm^.kbdPrint is also available as 
global variable SPKbd; this is the preferred interface for 
assembly language programmers). 


If you want to change the permanent value for some reason, 
you can modify the value of kbdPrint (or SPKba) and then 
call WriteParam to make the change permanent. See the 
"Operating System Utilities" of Inside Macintosh for more 


ist hex digit 
8 9 A BCD 
MESERERSESPRES 
NInnunnm 
2| 2 fel telet 
d|3 [Eli ]£]2 |V]".- 
|a (ales Pete 
"s For] fale 
x 6 [0|n|v|2 | A]. 
7 |áje|8| xj «|o. 
a| s [afe[e[n]- [1 
i o [a[6]o]x |. 
ij^ [8|]6| |I | w 
tB [|ajo|' |* |À 
Inngmun nem, 
D|c|u|«|O|Ó]| space 
E |é|à |/c| ele 
F [àjàüjO|o|o- 


Figure 3: Extended ASCII 


261 


details. 

Four of the keys on the keyboard are not considered to 
generate keycodes normally, but instead act as modifiers. 
These are the Shift, Caps Lock, Option, and Command key. 
The state of first three keys are mapped — along with the key 
struck — to generate an ASCII value. 

The Command key is always a modifier, and never affects 
the ASCII value. On the US keyboard, there are six modifier 
combinations that affect the ASCII mapping: 


(none) 

Caps Lock 

Shift 

Option 

Caps Lock-Option 
Shift-Option 


On the US keyboard, the Caps Lock is ignored if Shift is 
down, but there’s no guarantee that other keyboards will 
behave the same way. Note, however, your program can 
always detect if the Caps Lock key was down through the 
EventRecord.modifiers field. For example, the screen 
dump function key does this to distinguish Command-Shift-4 
(print current window) from Command-Shift-CapsLock-4 
(print entire screen). 


Function Keys 


A number of function keys are defined; they are listed in 
in Technical Note #3, “List of Command-Shift-Number 
Keys”. 

Function Keys #3 and #4 are contained as resources in the 


System file. Function Keys #1 and #2, which eject the disks, 
are presumably embedded in ROM. 

Some applications (such as a terminal emulator or macro 
processor) may want to map all key combinations, including 
the function keys. If you wish to disable the effect of function 
keys, then the following subroutine will modifiy global 
variable ScrDmpEnb to do the job: 


FUNCTION FKeyEnableCnew: BOOLEAN): 
BOOLEAN; 


TYPE 
boolptr = “BOOLEAN; 


ScrDmpEnb = $2F8; 
R 


old: BOOLEAN; 
bp: boolptr; 
BEGIN 
bp := BOOLPTRCScrDmpEnb); 
FKeyEneble := bp^; 
bp^ :* new; 
END; 


( current state ) 
( chenge state ) 


Passing TRUE to FKeyEnable will enable function 
keys (your program will not see these key combinations), 
while FALSE will allow your program to receive function key 
inputs. 

If you're trying to take full control of the keyboard, 
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Keyboard 
US classic 47 4 


you'll also want to turn off the Switcher control codes, 
Command-[,] and \ These are contained in ESCK #256 and 
CFIG #0 resources in the Switcher application. The byte at 
offset 1 (second byte) of the CFIG #0 disables keyboard 
switching if true. The ESCK with ID 256 contains the 
keycodes (which will be discussed later) and ASCII values for 
the characters that control switching, as described by the 
following Pascal data structure: 


TYPE 


ESCKRsrc = RECORD 
unused: Byte; 
swRightKc: Byte; 
SwLeftKc: Byte; 
SwBackKc: Byte; 
swRightChr: Byte; 
SwLeftChr: Byte; 


( right keycode ) 

( left keycode ) 

( back keycode ) 

( right ASCII cher ) 
( left ASCII cher ) 
END; 


Different Keyboards 


The original Mac 128 and 512 have a by now familiar 
keyboard, which, in the tradition of a certain beverage, I have 
dubbed the "classic" keyboard. For purposes of illustration, 
the keycaps for the original Mac are shown in Figure 4. (All 
keymaps show the unshifted output, except that letters are 
shown as capital letters.) 

The new Mac Plus keyboard is shown in Figure 5. Note 
the addition of the four arrow keys, and the disappearance of 
the right-hand option key. More significant is the 
disappearance of the Enter key from the main keyboard, as we 
will see in a moment. 

The various non-US keyboards are mechanically and 
electrically the same; all return the same keycode when you 
strike a particular key. However, the keycaps (hardware) are 
labelled differently, and the system disk contain different 
keyboard mapping procedures (software). The most successful 
foreign Macintosh market is France, so the key assignments 
for the original French keyboard are shown in Figure 6. 

There are three main differences between the US and non- 
US "classic" keyboard. The third row has an extra key, while 
the return is more vertical. Also, the lower left-hand corner 
has one additional key. 

Fortunately, the situation with the Mac Plus is much 
cleaner. The physical layout of all "new" keyboards is 
identical; in fact, some Apple documentation refers to this as 
the “universal keyboard", which should be reassuring to those 
developers who came to grief over the previous distinctions. 

If we distinguish between printing keys (including space), 
control keys (Return, Backspace, Tab, Enter), and modifier 
keys, this is how the various (main) keyboards compare: 


6 (2 Option) 
Euro-classic 48 4 6 (2 Option) 
Plus 47 8 (arrows) 4 (no Enter) 


You can see that the Plus is very similar to the US classic 
keyboard, but with one less Option key, a missing Enter, and 
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aot AX 
O KN AA 
€ o! ÁN 


v 


I" 


- v. ÁN 


{e X VA VA 
AN ZN ZN ZN 


Backspace 


VA AA 
OGOGO 


OOED 
DOOS 


Backspace 


AALALA AALALA 
Z NCN {ry Z VW 


PA o N ZN ZN 
VA VA VA VA VA 


ZN 


ELUR] 
cog 


DOD 
Occo 


AUN ZN 


Í O 


Figure 6: Mac Classic Keyboard 


(France) 


four additional arrow keys. 

Note that while particular keyboards are shipped with the 
corresponding Macs, there is no guarantee, for example, that a 
Mac 512 will have the original keyboard. Or, some users will 
pay for the Level 1 and Level 2 upgrades to a Mac 512, 
resulting in the hardware equivalent of a Mac Plus, but still 
use their original keyboard. 


© The Complete MacTutor, Vol. 2 


The only way to tell the two US keyboard types apart is 
the global variable KbdType. It contains the following 
values, which were empirically derived and don’t seem to be 
documented anywhere: 


KbdType=3 
KbdType=11 


classic keyboard 
new keyboard 
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Euro-Mac to 


Keycodes shown in italics are for 


49 52 


Option and Command keys for 


Keycodes shown in bold are common 


Keycodes shown in plain are for US 512 or 


Keycodes shown outlined are for 


Figure 7: Key code numbers (all 


Both the US and non-US original keyboards return a value of 
3, so it takes a little sleuthing to tell the difference. 


Key Mappings 


When the Macintosh boots, two of the INIT resources 
are reserved for establishing  nation-specific keyboard 
mappings. The INIT resource with ID #0 installs the main 
keyboard mapping routine in low memory and places a pointer 
to its entry point in KeylTrans. The INIT 1 resource does 
the same thing for the keypad mapping, storing its routine 
pointer in Key2Trans. 

These resources — and thus the software keyboard 
mappings can be changed by simply replacing the INIT 0 and 
1 resources. The Localizer (May 1985 supplement, disk “5/85 
MacStuff 1" provides the INIT resources for the following 
countries: 


US (256,257) 

UK (768,769) 

France (512,513) 

Germany (1024,1025) 

Italy (1280,1281) 

Sweden (2048,2049) 

Spanish/Latin American (2304,2305) 
French Canadian (3072,3073) 


The numbers shown in parentheses are the resource ID's of the 
corresponding INIT 0 and 1 resources in Localizer, if you ever 
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need to access them directly. 

The Localizer also changes other international parameters, 
and thus supports the Netherlands and Belgium. But these use 
the same keyboard assignments (hardware and software) as one 
of the previous eight countries. 

In fact, there are some suprises in the mappings, which 
do not follow expected political boundaries. The sun has set 


* Mac Plus keycode for 
this key always includes 
"Shift" modifier 


Mac 512 optional keypad (arrow keys are unshifted) 
vs Mac Plus standard keypad 


Figure 8: Keypad (US 512 vs. Plus) 
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on the British Empire, and this can be seen in those countries 
that share the same keyboard mappings: 


UK 

Ireland, Netherlands 
US 

Canada, Australia, New Zealand 
Sweden 

Norway 
France 

Belgium, french-speaking Switzerland 
German 

German-speaking Switzerland 


In Japan, Apple sells a version of the Macintosh called 
the DynaMac, which supports a subset of three ideographic 
character sets in use there. The Japanese user types words 
phonetically using one of about a hundred characters from one 
of the two Kana character sets, Katakana or Hiragana. Next, 
the software takes the combination of phonetic characters and 
guesses as to which of several thousand pictographic words 
(Kanji) is appropriate. As with English, the translation of 
phonetic to written spellings is approximate, using contextual 
information to distinguish between homonyms. 

The Kana and Kanji use the standard two-byte encoding 
scheme promoted by the Japanese Institute of Standards. 


Fr Canadian 


Italian 


Fig. 9 Partial comparison of US keyboards 


(cf. Fig. 6) 
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Spanish 


However, when not being used for the entering Kana, the 
ASCII keycodes generated by the DynaMac are identical to 
those of the U.S. (and Australian and New Zealand) Mac 512! 

In addition to setting the standard keyboard mapping, the 
Localizer also installs a new INTL resource; this includes a 
code that allows you to tell what the actual host country is. 
The KeyboardSleuth will use this to confirm its guesses. 

Note that installing the non-US key mappings (on a 
classic keyboard) won't do you any good unless you have one 
of the European keyboards. For example, with a French 
keyboard, I could use Localizer to try the U.K., German, 
Italian, etc. mappings, but the US keyboard was useless with 
these key mappings, and vice versa. Also, although the 
Localizer changes key mappings and the various international 
formats (date formats, month names, etc.), it does not translate 
applications or system software. Using Localizer on a French 
system disk allowed me to convince my test program that it 
was running on a Swedish system, but the Finder prompts 
were still in French! 


Generating Keycodes 


When you type a key, GetNextEvent returns the ASCII 
value of the key and its modifiers in the lower byte of 
EventRecord.message. The number of the primary key 


is also retumed in the next most significant 
byte, and can be found by the expression 


BitShift(BitAnd(msg, keyCodeMask),8) 


This key number is known as a keycode. 
These keycodes are the lowest level of 
information available to your program. 

The keycodes for the three previously 
mentioned keyboards are shown in Figure 7. 


Most of the key codes are common to all 
three keyboards. Where different, the key 
codes for the Plus and the non-US 512 are 
shown on the side. 

Figure 8 shows the keycodes for both 
the optional Mac 512 keypad and the Mac 
Plus's standard keypad. Note that the 
keycode for a 1 on the keypad is not the same 
as the keycode for the 1 on the main 
keyboard, although the ASCII value returned 
will be the same. 

There are three suprisingly major 
differences between the two keypads: 


* The “,” has become an “=”, 

e The numeric operators and their 
corresponding keycodes have been shuffled 
around. 

* The numeric operator keys return a “Shift” 
modifier, even when pressed without the 
Shift key. 
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This last feature is perhaps the oddest of all, but was done 
in the name of compatibility, so that although the arrow and 
numeric operator keys have been separated, no new key codes 
have been introduced. 

If you want to continuously monitor which keys are 
down, including detecting multiple primary keys down at one 
time (presumably for a game or an organ keyboard), the global 
variables KeyMap and KeypadMap are byte arrays 
containing a bit map (PACKED ARRAY OF BOOLEAN) 
indicating which keys are currently depressed. The “official” 
way to read these bit maps is to call Get Keys. 

Likely Problem Areas 
If there are incompatibilities between your Mac 512-based 


program and the other keyboards, here are where they are likely - 


to occur: 

Physical layout.. If you draw a map of the keyboard, you 
will have to change it, depending on the keyboard type, as 
shown in the figures. 

Different keycodes. Key #42 on the US machines 
produces “^”, while key #39 is a “Return”. On the non-US, 
#42 is “Return” and #39 is a printing character. The space and 
“Enter” keys are similarly reversed, while the bottom row is 
shifted over one. 

Different keycodes. Key #10 is accessible only on the 
non-US keyboards. Key #52 (US Enter) is not available 
anywhere on the Plus. 

Let’s look back at Mac Smalltalk, which expects click- 
Enter to simulate the “blue” (right) button of the original 
Xerox three-button mouse. This would be click-Space on the 
non-US Macs, but it is completely inaccessible on a Mac 
Plus. Fortunately, there’s another way to simulate the blue 
button in Mac Smalltalk, by clicking on the top edge of a 
Smalltalk window. 

National Idiosyncracies 

There are a number of significant differences between the 
various non-US keyboards. If you refer back to the French 
keyboard in Figure 6, you can see two notable differences from 
the standard US layout: 


* The top row does not produce numbers unless shifted; and 
* The layout is AZERT instead of QWERTY. Note also the 
M is to the right of the L, instead of on the bottom row. 


Oddly, the Italians follow the French form, except that 
the A and Q are reversed; both of these pattems are the same 
on the Mac Plus. 

Otherwise, the national differences are largely confined to 
the mappings of the 12 printing keys assigned to neither 
letters nor numbers. Figure 9 shows the output of the right- 
hand edge of the classic keyboard (unshifted) for six countries, 
which should be compared to the complete French keyboard 
shown in Figure 6. For the Plus, the key mappings differ yet 
again, although they are largely similar to those shown. 

We will use these mappings in building our keyboard 
sleuth. 

Identifying keyboards 
This following sample program identifies the keyboard in 
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use. It was written in Rascal, a real-time Pascal-like 
language developed at Reed College and distributed by 
MetaResearch (1100 SE Woodward, Portland, OR 
92702; price $129) Rascal includes a built-in 
development environment (editor, compiler, linker, executor), 
although not one as elaborate as LightSpeedC, which it 
predates. [The Rascal source is on the source code disk. The 
TML version is presented in the next article as a courtesy to 
our readership, most of whom do not yet have Rascal. -Ed.] 

I've tried to stick to the Pascal-like syntax as much as 
possible. KeyboardSleuth is short enough to translate into 
any language that includes a built-in assembler. (I don't have 
MDS, and didn't feel like hand-assembling the code in TML 
Pascal using $INLINE directives.) 

KeyBoardSleuth uses several techniques. First, it prints 
the country, as determined by the INTL resource. Second, it 
tells whether the classic Mac or Mac Plus keyboard is in use, 
by examining the keyboard type. 

If it is a classic keyboard, it decides whether this is a US 
or non-US keyboard. The best way is to check the keycode of 
the Space key, which differs between the two keyboards. For 
the various non-US keyboards, it looks at the keycode 
mappings by directly calling the keyboard translation routine. 
I used derived results to figure out which of the UK, France, 
French Canadian, German, Italian, Spanish or Swedish 
mappings have been chosen. (I don’t own a Mac Plus, so I 
didn’t have a chance to Localize it to each country to test 
sleuthing clues for telling its national keyboards apart). 

Fourth, KeyboardSleuth allows you to type keys and see 
what the result is; I used this to find out what the actual 
national mappings were. All the output is saved to a file, so 
you can print it out and examine it later. 
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Intermediate Mac'ing 


Typecasting Rascal to Pascal **9*° 


A Complete (nearly) TML Shell 


When I first saw this Keyboard Sleuth program, I 
thought, "How neat! But who has Rascal?", so after looking 
over the program, I figured I would just translate it into TML 
Pascal. Right! Three days and 60 hours later, I finally 
duplicated the program function in Pascal. In so doing, I 
gained an appreciation for how much work the development 
system shell in Rascal does for you, and how much 
programming effort must be spent typecasting variables in 
Pascal. Admittedly, I am an assembly language programmer, 
so when you tell me I need four bytes for a pointer, I don't 
care in the least what object the pointer points to. Not so in 
Pascal. Every time you turn around, you have to figure out 
some "magic" variable type to fool Pascal into letting you 
violate it's strongly typed variable rules. This is particularly a 
pain in the neck when dealing with the message field of the 
event record, since it's meaning changes (and hence it's type!) 
with each different event, even though it's length of course is 
always four bytes, or LONGINT. If I had understood 
typecasting better, the conversion would have been much 
easier. Whoever thought strongly typed variables would make a 
programmer's life easier never had to program for a living. 
Macintosh programs would decrease in size and complexity 
dramatically if mixing of variable types was both allowed and 
automatic by the compiler. This is one area where a good 
Basic compiler could really make toolbox programming 
simple and quick. (Perhaps that is the appeal of a langauge 
like Rascal in the first place!) Here are some typecasting rules 
that should make this easier for you than it was for me. 


Typecasting on the Mac 


Types in the Macintosh: 


SignedByte: any byte in memory (-128..127) 
Byte: unsigned byte (9..255) 

Ptr: a pointer or address (^SignedByte) 
Handle address of a Ptr (*Ptr) 


The Signed Byte is the fundamental type. Any size of 
bytes of memory can be created as a pascal data structure using 
the following: 


Packed Array[1..size] of SignedByte 


I'm still not sure what a string is, but the Macintosh 
string type is Str255, which is defined as STRING[255], 
which I finally found out on page I-91 of Inside Macintosh, 
means a four byte pointer to what I assume is a packed array 


of char that can be up to 255 characters in length. A byte 
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David E. Smith 


ardS leuth Editor & Publisher 


Part 2 


Keyboard Sleuth (TML Version) 


Main  [ 
Program [ 


Fig. 1 Our Top Down Structured Program! 


length count is added at the beginning for a total size of 256 
bytes. This was my assumption in the program, and it seems 
to work. So everytime you see Str255 in a program, it's not 
really the string, but a four byte ptr to the length byte of the 
string. 

To get around the type casting problem for a pre-defined 
Pascal type, you do something like this: 


Var 

key: Byte 

code: Char 
Begin 

key:=Byte(code); (types must be same length) 

This forces code, which is a Char type into Key, which is 
a Byte type, by "reminding" Pascal with the Byte designator, 
that key is of type Byte. You'd think the compiler could figure 
that out for himself! 


Fig. 2 The mouse event 
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Fig. 3 Menu bar commands 


For non-predefinded types, it gets more complicated. 
Basically you have to create something in an allowed type and 
then force it into your type. The example below shows how to 
peek at a byte location in memory. We create a Handle (which 
always points to a signed byte), then typecast it into the 
Handle we really want (magicHandle), then use another Pascal 
mystery, the case boolean of, to equate the four byte 
LONGINT type to four individual bytes of Byte type so we 
can read a single byte. This is the most magic of all. It seems 
as if it violates the fundamental law of the universe, by 
making TRUE and FALSE both valid at the same time! I 
guess only a computer could accomplish that. 


Peeking into Memory 


Type 
magicHandle = “magicptr; 
magicptr = “magic; 
magic = packed record 
case boolean of 
true: CL:LONGINT); 
false: Cbyte3, byte2, byte 1, byted : Byte) 
end; 
Var 
tempHendle: ^ Handle; (to signed byte) 
nagicman: magicHendle; ^ (this seems magic to me) 
addr : integer; 
nysize: integer; 
Begin 


eddr:-$021E; (some place in memory to peek) 
nysize:-SIZEOF(magicman); 
tempHandle:-NEWHANDLECmys ize); 
magicman:=magicHandle( tempHandle); 
magicman^ :=pointer(Caddr ); 
KbdType :=magicman** .byte3; 
disposHandleCtempHandle); 
End; 


(typecasting!) 
(nore typecasting!) 
(Finally!) 


Inside Macintosh says strong typing ability lets Pascal 
programmers write programs without really considering the 
size of variables (page I-86), which would be an advantage if 
we were writing Pascal programs. But on the Mac, you really 
write toolbox programs, which are assembly programs, which 
requires you to know the length of each type, which requires a 
lot of typecasting (I guess). If anyone else has an explanation 
of why we should ever have to typecast same length variables, 
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Id ike to hear it. 

The final problem is one of incrementing or decrementing 
an address in memory so you can point somewhere else. This 
gave me fits until I learned how you do it. First you convert 
the pointer back into a number (it wasn't already?). Then you 
do your number thing on it (add, subtract, etc.) Then you 
convert it back into a pointer. A whole set of functions let 
you do all this mashing of types. Here they are from page I-80 
of Inside Macintosh: 


Var 

enInteger: INTEGER; 

ALongInt: ^ LONGINT; 

ePointer: Ptr; 
Begin 
anInteger: = ORDCaLongInt); (two low bytes) 
anInteger := ORDCaPointer); (two low bytes} 
aLongInt:s ORDCanInteger); (packed in high order) 
aLongInt:= ORD4CanInteger ); (packed in low order) 
aLongInt:= ORDCaPointer); (make ptr a number) 
aPointer := POINTERCanInteger); {make into an address) 
aPointer := POINTERCaLongInt); (make into an address) 
end; 


The POINTER function converts a number into an 
address. So to increment an address, you: 


NewAddress:=POINTER(ORD(@Str)+1); 


This converts the pointer to the string to a LONGINT 
number, allowing you to increment it by one, and converts it 
back to a pointer. Now you've learned what took me 60 hours 
of Mac study to figure out. Namely how to point to the string 
data past the length byte. If it's old hat to you, then you're a 
Mac Hacker of long standing. If it's new, then welcome to the 
Macintosh world. 


How Do You Print a String? 


The main thing that Keyboard Sleuth does is poke around 
in the Mac and try and figure out what kind of keyboard you 
have. Then it prints all the information to the screen and a log 
file and sits in a loop waiting for you to press a key. When 
you do, it zaps out a message of what key number you pressed 


Fig. 4 Key press event routine 
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and what it's ascii value is and displays the character itself, if 
it's not a control character. So the main idea is to display back 
a lot of information to the user. How do you do that on the 
Mac? If you look at all the Mac programming books, and I've 
been through them all, generally they all assume its the user 
that wants to display stuff on the screen, not the program. In 
Rascal, it's easy as the following example shows from our 
program. 
Rascal PutString Procedure 


Procedure PutString(str: PtrB); 
BEGIN 


writestring(str); (* to the screen *) 


IF logfile THEN 


fPutSClogfile, str); — (* to the file *) 


Making the Simple into the Complex 


What they don't tell you is a lot of housekeeping is done 
on the Mac for you. For example, if you print a bunch of stuff 
on the screen, what happens when you get to the bottom of 
the screen? Oh, you mean you want scrolling? Well, that's a 
horse of a different color. Or suppose someone opens the 
calculator DA, and your list is obliterated. Oh, you mean you 
want updating? That's TextEdit. Or suppose you want to save 
the data you displayed for the user. Oh, you want files? Well 
better go see standard file dialog about that! Or suppose you 
want to back up so the user can see what you printed out for 
him, Oh, well, you better get some controls then and handle a 
scroller event. And on and on it goes until 
your simple Print "hello world" becomes a 
full blown mac application. Such is what I 
got caught up into when I started 
converting this program to Pascal. I quit 
when I got to scrolling and saved controls 
for another day! 


-4(A6) 
$8F6A2 (A6) 
4(A6) 
8(A6) 
12(A6) 


Pascal Version of PutString 


Take a look at the procedure PutString 
in our Pascal program listing and you will 
see all of these issues we've discussed. We 
insert the text, pointing to the string data, 
not the length, into our text edit record. 
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$8F68A SP 


This basically gets the data on the 
screen. Then we check to see if we 
have reached the end of the screen, 
by looking at the line counts 
times the character height from 
the text edit record. In this way, it 
still works if someone changes 
fonts later. If we need scrolling, 
we scroll up, again using the 
character height as a scroll value. 
The TEInsert writes our text to 
the screen, and generates a new 
update event if the insertion 
changes anything downstream, 
which is doesn't in the case of 
printing lists. 


KeyTrans Assembly Routine 


The final problem had to do with the keytrans routine. 
This routine pokes around for the correct ROM routine to 
translate a key code into ascii. The clever thing is that this 
routine changes depending on what your country is, So by 
installing custom translation routines, you make custom 
Macs. By using this Mac routine to convert to ascii for us, we 
can see what character is returned and guess at the keyboard 
type. To do this we have to call a machine language routine. 
So keytrans is an assembly glue routine that allows us to call 
a Mac routine and return the results back to Pascal. This led to 
more investigations on how to call assembly from Pascal and 
how to call Pascal from assembly. The key to it all is the A6 
frame pointer. How it works is shown in the figure below. 


File Stuff Not Polished 


Be aware that the file routine in OpenLog is very 
primitive and doesn't do anything with the error Checking. I 
had the program bomb on me once or twice for some reason 
after the standard file dialog, so you should put some effort 
into beefing up the error checking coming back from the 
various disk I/O routines. This is a great little Mac demo 
program that is both useful and makes a good shell program 
showing off file I/O, text edit and scrolling. I learned a lot 


Tar AAs) 


high memory 


Dataarea 
Previous A6 value 

Pascal return address 

stack based parameters, second, first 
Function result if any 

Previous stack contents 


Stack 


Snooping 
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from it. Thanks Joel! 


Open [ 
Log File 


Get File B | Get File [ 
Name, Volt Info f 


Put Ai : 
File Dialog] 


Check for F 
TEXT type] 


mn ST Set File } 
Position $ 


program KeyboardSleuth; 


( Keyboard Sleuth: analyze key mappings 
Stand-alone version written in Rascal 
By Joel West, August 1986, for MacTutor 


** Converted to TML Pascal by David E. Smith ** 


Tries to figure out what keyboard is installed 
Uses several approaches: 
-Dump and analyze keyboard #8 
-Check keypad for Mac 512 vs. Mac Plus 
-Look at INTL resources to find for country code 
-Check for mapping of space key CUS vs. Foreign) 
Then allows user to type keys and shows their keycodes 
and ASCII values. Dumps this to screen end to a logfile ) 


( Include files and constants ) 


($1 MemTypes.ipas ) 
($I QuickÜrew.ipas ) 
($I OSIntf.ipss — ) 
($I ToolIntf.ipas ) 
($I PackIntf.ipas ) 
($I HFS. ipes ) 


( -——--7—-7-—-——---- GLOBAL CONSTANTS ------------ ) 

CONST 
KeyiTrans = $29E; ( Low Memory Globals ) 
Key2Trans = $2A2; 
EOL = 13; ( end of line file delimiter (RETURN) ) 


(nenu res id's ) 
AppleMenu = 256; 


FileMenu = 257; 
EditMenu = 258; 

(ames ASCII values ------------ ) 
Space = $20; 


( Key #18, where US,UK "/" is (key ® differs in US) ) 


Slash = $2F; (/ UK 
Minus = $20; (- German, Spanish, Swedish 
Equals = $3D; (= French } 
Ograve = $98; (` Italian } 
Eaigu = $8E; { ’ French Canadian } 


( Key ® 36, where UK "`" Caccent grave) is 
Used only to distinguish Spanish from German and Swedish ) 
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Do My Stuff 


en E 
lion File F 


Degree = $41; (9  Spenish/Latin American ) 

Hash = $84; (* German 

Apos = $21; (` Swedish ) 
pa Keycap Numbers ------------ ) 


USspKey = 49; 
UKspKey = 52; 
UKslKey = 18; 
UKgrKey = 36; 


( space bar in US ) 

( space bar in UK, EuroClassics} 
( / key in UK } 
( ` (dead) key in UK } 


( ---------------- GLOBAL VARIABLES ------------ ) 


VAR 

(ny stuff) 

mywindow: WindowPtr; { our window pointer ) 
finished: Boolean; (program terminator) 
ClockCursor:CursHandle; (handle to waiting watch ) 
(STDFile stuff) 


logfile: INTEGER; ( file status ) 
logname: STR255; ( file name } 
volNumber: INTEGER; ( vRefNum ) 


fileNumber: INTEGER; 


( file number ) 
(Screen stuff) 


DregArea: Rect; 

GrowArea: Rect; 

Screen: Rect; (holds the screen dimensions } 
(TextEdit stuff) 

DestRect: Rect; 

ViewRect: Rect; 

theText: TEHandle; 

scrollflg: Boolean; 

( ---------------- BEGIN CODE ------------ ) 


Function KeyTrensCkeyno, modif ies: Integer) : Integer; 
EXTERNAL ; 

($U keytrans ) 

( Translate key number and modifiers to 
their corresponding ASCII value ) 


Function CR:str255; 
begin 
CR:= chr(E0L) 
end; 


PROCEDURE Openlog; 
( open keyboard logfileto save all messages for later review ) 


lebel 1; 
Var 
where: Point; 
Prompt: STR255; 
origNeme: STR255; 
reply: SFReply; ( standard file reply record ) 
Info: FInfo; (Finder file info reply record ) 
vol: INTEGER; ( vRefNum ) 
f ileno: INTEGER; ( file number ) 
resultCode: OSErr; 
Begin 
where.v := 50; 
where.h := 50; 
Prompt := 'Seve your log file as: '; 
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origName := ‘KeyBoard Log'; Var 


DILoed; (in cese disks are switched) resultCode: OSErr; 
SFPutFileCWhere, Prompt, origName, Nil, reply); strlen: LONGINT; 
logname := reply. fName; scrollup: integer; 
vol := reply. vRefNum; curlines: ^ integer; 
IF reply.good = FALSE THEN linepos: integer; 
logfile := Ø (bad file) newpos: integer; 
E endpos: integer ; 
logfile:= 1; (good file} BEGIN 
IF logfile = Ø THEN goto 1; strlen:=length(str); 
TEInsert(POINTERCORD(@str )+1),strien, theText); 
resul tCode:=GetFInfo Clogname, vol, Info); TEIdleCtheText); 
case resultCode of HLockChandleCtheText)); 
IF (not scrollflg) then 
NoErr: (file exists..delete it ) begin 
Begin scrollup:-theText^^. lineHeight; 
if Info.fdType € 'TEXT' then curlines:stheText^^ .nL ines; 
begin linepos:zcurlines*scrollup; 
logfile:20; endpos :=theText** .ViewRect bottom; 
goto 1; if Clinepos»=endpos) then 
end; scrollflg:=true; 
resul tCode :=RstF lock( logname, vol); end; 
if resultCode € NoErr then if scrollflg then TEScro11C2, -theText^^.lineHeight, theText) 
begin HUnlockChandleCtheText)); 
logf ile:-0; IF logfile = 1 THEN 
goto 1; Begin 
end; resultCode:- FSWrite (fileNumber, strlen, 
resul tCode :=FSDelete( logname, vol); POINTERCORD(@str )+1)); 
if resultCode € NoErr then if resultCode € NoErr then logfile:=0; 
begin End; 
logfile:=0; END; 
goto 1; 
end; Function IntToString(num: Integer ):str255; 
resultCode:= Create Clogname, vol, 'MACA', 'TEXT'); (integer to string) 
if resultCode © NoErr then VAR 
begin S: Str255; 
logf ile:70; longnum: LongInt; 
goto 1; BEGIN 
end; longnum:-num; 
end; NumToStringClongnum, s); 
FNFErr: ( file not found so create one ) IntToStr ing:=s; 
begin ; 
resultCode:= Create Clogname, vol, 'MACA', 'TEXT' 5; 
if resultCode «€? NoErr then Function KbdType: Integer; 
begin ( Get low memory value at $21E, a byte, the keyboard no. ) 
logf ile:28; Type 
goto 1; nagicHendles^magicptr; 
end; magicptr = “magic; 
end; magic = packed record 
OTHERWISE logfile:=0; case boolean of 
End; ( case true: (1: longint); 
if logfile = @ then goto 1; false: (byte3,byte2,bytel,byte: Byte) 
end; 
resultCode:- FSOpen Clogname, vol,fileno); ( open log file ) Var 
if resultCode © NoErr then tempHandle: Handle; (handle to signed byte) 
begin magicman: ^ magicHendle; (handle to magic) 
logfile:20; addr : INTEGER; 
goto 1; nysize: INTEGER; 
end; 
resultCode:- SetFPos (fileno, FSFromStert, 0); BEGIN 
if resultCode © NoErr then addr := $021E; 
begin mysize:=SIZEOF Cmagicman); 
logfile:20; tempHand1e :=NewHandle(mysize); 
goto 1 magicman: -magicHendleCtempHandle); 
end; nagicman^ :-pointerCaddr); 
volNumber :=vol; KbdType :=magicman** .byte3; 
f i leNumber :=f i leno; disposHendleCtempHandle); 
ii j 
if logfile = 1 then 
SetWTitleCmywindow, logname) Procedure ShosIntlNation; 
else ( Show ) 
SetWTitleC(nywindow, 'No Log File!'); VAR 
; country: integer; 
ih: intlgHndl; 
Procedure PutString(str: Str255); s:str255; 
( Write a string to the log file and to the screen ) known: Boolean; 
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BEGIN 
ih := intlgHndlCIUGetInt1C022; ( get INTL Ø resource } 
country :=Cih**.int]@Vers) div 16;( country is upper byte ) 
s:='This Mac is configured for '; 
known:=true; (be optomistic) 


( There are symbolic constants for these (verUS, verFrence, 
etc.), but unless even if you have the latest update to your 


development system, you probably won't have al] 26. I've hard- 
coded them for clarity. 
CASE country OF 
0:  S:-concat(s,'the US or Canada’); 
1: s:=concat(s, 'Frence'); 
2: s:=concat(s, 'U.K. or Ireland’); 
3: s:=concat(s, ‘Deutschland’ ); ( Germany ) 
4:  S:7concat(s, 'Italia'); 
5: s:=concat(s, 'Nederlend'); ( Netherlands ) 
6: s:=concat(s, 'Belgique ou Luxembourg ' ); 
7:  S:z7concat(s, 'Sverige'); ( Sweden ) 
8: s:=concat(s, 'Espe^' '); ( Spain ) 
9: s:=concat(s, 'Denmark ' 5; 
18: s:=concat(s, ‘Portugal’ ); 
11: s$:=concat(s, ‘Quebec’ ); ( French Canada } 
12: s$:=concat(s, 'Norge '); ( Norway ) 
13:  s:zconcat(s, 'Yisra’el'); 
14: $:=concat(s, 'Nippon'); ( Japan } 
15: s:=concat(s, ‘Australia or New Zealand’); 
16:  s:»concat(s, 'Arebigah' ); 
17: s:=concat(s, 'Suoni ' 5; ( Finland ) 
18: s:=concat(s, 'Suisse'); ( French Swiss ) 
19: Ss:zconcat(s, 'Schweiz '2; ( German Swiss ) 
20:  S:-concat(s, 'Ellas'); ( Greece ) 
21: s:=concat(s, ' Islend'); ( Icelend ) 
22: s:=concat(s, 'Malta'); 
23: s:=concat(s, 'Kypros' ); ( Cyprus ) 
24:  S:zconcat(s, 'T rkige' 5; 
25:  s:zconcat(s, ' Jugoslavi ja 2; 
OTHERWISE 
Begin 


known: false; 
S:*concat(s,'an unknown country, *',IntToStringCcountry2, ' .' 2; 
End; 
END; (cese) 
if known then s:=concat(s,'. °); 
S:*concatCs, CR, CR); 
PutString(s); 
END; 


Procedure ShowModel; 
( Guess which type of Macintosh keyboard ) 
Var 


s,ss:str255; 
Kod: INTEGER; 
BEGIN 
( Use derived keyboard numbers } 
Kbd:=KbdType; 
ss:=IntToStr ing(Kbd); 
$:=concat('The keyboard type is 
CASE Kbd OF 
11: s:=concat(s,', which is a Mac Plus keyboard.'); 
3: s:=concat(s,', which is the Classic Mac 
keyboard. ' 2; 
OTHERWISE — s:sconcat(s,', which is unknown. '); 
END; (case) 
s:=concat(s, CR); 
PutString(s); 


Lr] 
4 


,88); 


tion; 
( Guess which country keyboard mappings are set for ) 
Var 
s: str255; 
GIN 
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( Try mapping of certain keys to figure US vs. non-US board ) 
IF (KeyTransCUSspKey,0) = Space) THEN 
begin 
s:='This is US, Canadian or down under.'; 
end (IF... THENS 
ELSE 
BEGIN 


IF CKeyTrans(UKspKey,9) = Space) THEN 
BEGIN 


( Use UK "/" key to guess at nationality ) 

CASE KeyTrans(UKs1Key,9) OF 

Slash: K 

s:=concat(s, 'I am British or Dutch.'); 

Ograve: (` Italian } 
s:=concat(s, ‘Sono Italiano. '); 

Equals: (= French ) 

s:=concat(s, 'Je suis fran,ais, suisse ou belge.'); 

Eaigu: ‘French Canadian } 
s:=concat(s, ‘Je suis canadien. '); 

Minus: (- German, Spanish, Swedish ) 


( Use UK accent grave (dead `) to tell 
German, Spanish, and Swedish ) 


CASE KeyTrensCUKgrKey,2) OF 
Hesh: German 
s:=concat(s, 'Ich bin ein Deutscher. '); 
Degree: (, Spanish 
s:=concat(s, ‘Habla Espa”ol.'); 
Apos: (^ Swedish  ) 
s:-concat(s,'This is Swedish. '); 
OTHERWISE — ( I have no country! ) 
s:=concat(s,' iNo tengo un pa's!'); 
END; (case UKgrKey) 
OTHERWISE 
begin 
S:-concat(s,'I am a Mac without a country! '); 
end; (otherwise) 
END; (CASE) 
END (IF...THEN) 
ELSE 
begin 
s:=concat(s, 'Neither US nor European, what is it?'); 
end; (else) 
END; (IF . . THEN. .ELSE) 
s:=concat(s,CR,CR, 'Type keys, or click mouse to quit. ', CR); 
PutString(s); 


END; (proc) 

Procedure Doltuff ; 

an 
s: str255; 

BEGIN 
OpenLog; ( log file ) 
ShowIntlNation; ( Find country code ) 
ShowMode1 ; ( Examine keyboard type ) 
GuessKeyNat ion; ( Look at key mappings ) 


showW indow(mywindow); 


) 
(Following is standard Mac Shell stolen from TML Examples) 


PROCEDURE DoMenu(se lect: longint); 


Var 

Menu_No integer; 

Item_No: integer; 

NameHolder: Str255; (DA or Font name holder } 

DNA: integer; (OpenDA result 
Begin 

If select <> Ø then 

begin 

Menu-No := HiWord(select); (get the Hi word of...) 


Item.no := LoWord(select); 
Case Menu.No of 
AppleMenu: 


(get the Lo word of...) 
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Begin 
Get I tem(GetMHandleCAppleMenu), Item_No, NameHolder); 
DNA := OpenDeskAcc(NameHolder ); 
End; (applemenu) 
FileMenu: Finished:=true; (quit) 
EditMenu: 
Begin 
If Not SystemEditCItem.no - 1) then 
Case Item. No of 


1: begin end; (undo) 
( 2: line divider) 
3: TECutCtheText); (cut) 


4: TECopyCtheText ); (copy) 
9: TEPesteCtheText ); — (paste) 
6: TEDeleteCtheText 2; (clear) 
End; (case) 
End; {editmenu} 
end; (case menu. no) 
HiliteMenuC0); 
end; (If select © Ø 
End; (of DoMenu procedure) 


PROCEDURE doMouseDowns(Event :EventRecord); 


(unhilite after processing menu) 


Var 
Location : integer; 
WindowPointedTo :WindowPtr; 
MouseLoc :Point; 
WindoLoc : integer; 
Begin 


MouseLoc := Event.Where; 
WindoLoc := FindWindow(MouseLoc, WindowPointedTo); 
Case WindoLoc of 
inMenuBar : DoMenu(MenuSe lect (MouseLoc)); 
inSysWindow: SystemC] ick(Event, WindowPo intedTo); 
inContent: 
if WindowPointedto © FrontWindow then 
SelectwWindow(WindowPointedTo); 


inGrow: Begin End; (no grow) 
inDrag: DragWindow(WindowPointedTo, MouseLoc, Dr agr 
ea); inGoAway 
Begin 
If ae ackGoAwagCW indowPo intedTo, MouseLoc) then 
egin 


DisposeW indow(WindowPointedTo); 
f inished:=true; 


End; 
End; (inGoAway) 
End( of case); 


I 


PROCEDURE doKeyDowns(Event :EventRecord); 
Type 

nagicHandles^magicptr; 

magicptr = “magic; 

magic = packed record 

case boolean of 
true: (1: longint); 

false: Cbyte3, byte2, byte 1:Byte;chrd: Char) 


end; 
Var 
CharCode: char; 
keycode: Byte; 


mods: INTEGER; 
S: str255; 
keyc: INTEGER; 
asc: INTEGER; 


tempHandle: Handle; (handle to signed byte) 


magicman: ^ magicHandle; (handle to magic) 
nysize: INTEGER; 

Begin 
nysize : :SIZEOF C(magicman); 
tempHandle :=NewHandle(mysize); 
magicman :zmagicHendleCtempHandle); 


magicman^^.1 :-Event message; 
CharCode :magicman^*^ .chr£; 
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keycode :=magicman^ ^. bytel; 
keyc := keycode; 
mods := Event.modif iers; 


S:=concat('Key #',IntToStringlkeyc)); 


IF BitAnd(mods,optionKey) = optionKey THEN 
S:7concat(s,' with Option'); 


IF BitAndCmods,shiftKey) = shiftKey THEN 
S:-concat(s,', shifted'); 

IF BitAnd(mods,alphaLock) = alphaLock THEN 
S:-concat(s,', Caps Locked'); 


asc := KeyTrans(keyc, mods); ( try trenslate to ASCII ) 
( Don't want to print contro! characters ) 
IF asc >= 32 THEN 


BEGIN 
S:-concat(s,' is ',chrCasc),' Cascii 
', IntToStringCasc),').'); END; 
s:=concat(s,CR); 
PutString(s) 


I 


PROCEDURE doActivates(Event: EventRecord); 
Var TargetWindow:WindowPtr; 
Begin 
TergetWindow := pointer Cord4(Event .message )); 
If OddCEvent modifiers) then 
Begin (activate) 
SetPort(TargetW indow); 
End 
else (deactivate) 
Begin End; 
End; 


PROCEDURE doUpdates(Event :EventRecord); 
Ver 
UpDateWindow,TempPort: WindowPtr; 
in 


UpDateWindow := pointerCord4CEvent .message)); 
if UpDateWindow = mywindow then 


Begin 
GetPort(TempPort); (Save the current port) 
SetPort(mywindow); (set the port to one in Evt.msg) 


BeginUpDateCmyw indow); 
EreseRect(myw indow^ . visRgn^^ .rgnBBox2; 
TEUpdate(myw indow* . visRgn^^ .rgnBBox, theText); 
EndUpDate(mnyw indow); 
SetPortCTempPort); 
End; 
PROCEDURE EndProgran; 


Var 
resultcode: OSErr; 


(restore to the previous port) 


n 
IF logfile 21 THEN 
begin 
resultCode:- FSCloseCf i leNumber 2; 


end; 
ExitToShel1; 


/ 


PROCEDURE MainEventLoop; 
Var Event:EventRecord; 
DoIt: Boolean; 
Begin 
InitCursor; 
Repeat 
SystemTask; (support DAs} 
DoIt := GetNextEvent(EveryEvent, Event); 
If DoIt(is true) then (we'll DoIt) 
Case Event.what of 
mouseDown =: doMouseDowns(Event); (1) 
mouseUp : begin end; {2} 


273 


KeyDown : doKeyDowns (Event); (3) 
keyUp : begin end; (4) 
autoKey : begin end; (5) 
updateEvt — : doUpdates (Event); (6) 
diskEvt : begin end; (7T) 


activateEvt : doActivates (Event); (8) 
(ebort evt now reserved for future) i 
À 


networkEvt  : begin end; 

driverEvt — : begin end; (B) 
app lEvt : begin end; (C) 
app2Evt : begin end; (D) 
epp3Evt : begin end; (E) 
app4Evt : begin end; (F) 


End; (of Case) 
Until Finished; (end progrem) 
EndProgrem; (call our finish up stuff) 


s 


PROCEDURE InitThings; 
Begin 

InitGraf C@thePort); 

ClockCursor := GetCursor(CwatchCursor ); 
HLockCHandleCClockCursor )); 
SetCursor(ClockCursor**); 

InitFonts; 

Ini tWindows; 

Ini tMenus; 

TEInit; 

InitDialogs(Nil); 

FlushEventsCeveryEvent, ø); 

scrollflg:=false; {too early to scroll!) 
finished:=false; (clear program terminator) 


é 


PROCEDURE SetupL inits; 

Begin 

Screen := ScreenBits.Bounds; (screen 512 by 342 pixels) 

SetRect(DregAree, Screen. lef t+4, Screen. top*24, 
Screen.right-4,Screen.botton-4); 

SetRect(GrowArea, Screen. lef t, Screen. top*24, 
Screen.right,Screen.bottom); 


d 


Procedure Setup indows; 


Const 

sbarwidth=16; (width of scroll bars} 
Var 

myrect: Rect; 

windtype: integer; 

Visible: boolean; 

GoAway boolean; 

Ref Val LongInt; 
Begin 


SetRect(myrect, 10,40,500,330); ( window size -global cord) 
windtype := 4; set window type - nogrowdocproc } 
Visible := false; (set the window to invisible } 
GoAway := true; (give the window a GoAway box } 
mywindow:= NewWindow(Nil, ( allocate space in Heap) 
myrect, 
‘Keyboard Sleuth', 
Visible, 
windtype, 
POINTERC- 12, 
GoAway, 
RefVal); 
SetPor t(mywindow); 
TextFont(Geneva); 


(front) 
( goaway region in title area ) 
( 32-bit value used by App) 


( Set Up Text Edit Record for this Window ) 


with myWindow^.portRect do 

SetRect(ViewRect,4,4,right-Csbarwidth- 1), 
botton-Csbarwidth- 122; 

DestRect:=ViewRect; 

theText:= TENew(DestRect, ViewRect); 
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( NOTE: NewWindow initiated an ActivatEvt and an ) 
( UpDateEvt event. Being queued up by event manager.) 


a 


PROCEDURE Se ; 
Ver myMenu :MenuHandle; 
NemeHolder :STR255; 
Begin 
myMenu := GetMenu(AppleMenu); (from resource file) 
AddResMenu(myMenu, ‘DRVR'); {adds DAs} 
Inser tMenu(myMenu, 2); 
myMenu := GetMenu(FileMenu); (Quiting...) 
Inser tMenuCmyMenu, 2); 
myMenu := GetMenuCEditMenu); (DA support...) 
Inser tMenuCmyMenu, 9); 


ÜrewMenuBar ; (show the menu bar} 


IN 

InitThings; 
SetupLimits; 
SetupWindows; 
SetupMenus; 
DoMyStuff ; 
MainEventLoop; 


(do first so its low in heep) 


; EXAMPLE ASSEMBLY SUBROUTINE 
; key test thing 

; VERSION 11 July 1986 

; CC) Copyright 1986 MacTutor 
INCLUDE MACTRAPS .D 


XDEF keyTrans ; required for linker 
j 55333223532 System globals sZzZZZZzzzzzzzz 

Key 1Trans equ $29E; ( Low Memory Globals ) 
Key2Trans equ $242; 


KeyTrans: 

; key code (2 bytes) and modifiers (2 bytes) passed 
; ascii char code returned (2 bytes) 

link a6, 8-4 

movem.1 A@-A1/D®@-D2, -CSP) 

; get key code from stack into D2 

; get modifiers from stack into D1 


move.w — 8CA6), D1 ,Second parameter (modifiers) 
move .W 1ØCA6), D2 ;first parameter (key code) 
move .w #9, DØ ;Shift count for flags 

Isr Dd,D1 ;move bits to lower byte 

andi 87, DI ,nesk 3 bits to get modify in D1 
cmpi 864, D2  ;keycode «64 then key! 

BGE key2 ;=64 then key2 

key 1: 

clr.1 D8 

LEA showit, AØ ,get return address 

move. | AQ, -CSP) ,return address to stack 
move. | ®keyltrans, A8 ;global for ptr to keyitrans 
move. 1 CAB), AG ,get address of keyltrans 

pp (A0) ;call subroutine 

key2: 

subi #64, D2 ,edjust key code 

clr.1 DØ 

LEA showit, AQ jget return address 

move. | A80, -CSP) ;return address to stack 

move. | Skey2trans, Að ;global for ptr to key2trans 
move. ] CAG), A0 ;get address of keyitrans 

jmp (A0) ;call subroutine 

showit: 

; return function result from DO 

move.w DØ, 12CA6) ,pess back function result 
movem.] (SP)+, A0-A1/D0-D2 

unlk a6 
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move. | (SP)*, AQ 
addq.1 — 84, SP 


* Sleuth.R 
x 


Sleuth/Rsrc.Rel 
Type DAV1 = STR 


END OF PROGRAM 


D. Smith & J. West 


Type FREF 
APPL Ø 
Type BNDL 


DAVI Ø 
ICN® 
0 128 
FREF 
Ø 128 


Type MENU 


* the desk acc menu 


4 


\14 


* the file menu 


,251 
File 
Quit /Q 
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* the edit menu 


,get return address 
,remove passed parameters 


Type ICN* = GNRL 
,128 (32) 
H 


001F C000 
0060 2000 
0080 1000 
011F 8800 
0120 4400 
0240 2200 
0240 1200 
0280 1200 
0380 1200 
0000 1200 
0000 2200 
0000 2400 
0000 4400 
0000 8800 
0001 1000 
0002 2000 
0004 4000 
0004 8000 
0004 8000 
0004 8000 
0004 8000 


0004 8000 
SFFF FFFC 
760B 6DBA 
B6DB 6DB9 
8000 0001 
BB6D B6DF 
BB6D B6DF 
8000 0001 
B6FF FEED 
76FF FEEE 
SFFF FFFC 
x 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 


FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 
FFFFFFFF 


PAS$Xfer 


/Globals -4 


Sleuth 


PAS$Library 
OSTraps 
Tool Traps 
PackTraps 
keytrans 


/TYPE ‘APPL' 'DAV1' 
/BUNDLE 

/RESOURCES 
Sleuth/Rsrc 


Link File 
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Advanced Mac ing 
Build a Pop-Up Window Scroller 


Getting the Big Picture 

For years computers offered no more user interface than a 
command line, single-keystroke menus, and full-screen text 
editing. The Macintosh has introduced us to the beauties of 
carefully designed user interfaces. The average user has come 
to expect pull-down menus, windows, a desktop, a pointing 
device, and other user interface tools. Apple has provided a set 
of guidelines for those who would like to extend the user's 
mental metaphor by providing new user interface elements. 

Many solutions emerge out of the minds of frustrated 
users. For example, users of large computers used to have all 
computer output displayed on one screen in a single stream of 
characters. This really was not a problem until users realized 
they could have more than one thing going at once. To help 
users sort out what came from where, windows were born. 
Each window contains information relating specifically to the 
topic of interest of that window. For example, if you are 
editing a document in one window, you could receive mail 
messages in another while watching system utilization in yet 
another. Thus, since someone got frustrated with having 
input and output streams all mixed into one, windows now 
allow separating these streams in a sensible manner. 

One element of the Macintosh interface that can be 
frustrating is the manner in which scroll bars operate, 
especially if the window uses two scroll bars, one for vertical 
and the other for horizontal movement. In the extreme case, 
consider a window containing a very large picture which takes 
a substantial amount of time to redraw whenever you move 
around with the scroll bars. If you are positioned at the top- 
left corner and want to move to the bottom-right corner, you 
are obligated to do one of two things. 

First, you can move the cursor all the way to the bottom- 
left of the window and drag the horizontal thumb all the way 
to the right, move to the top of the vertical scroll bar, and 
move its thumb all the way to the bottom. This approach 
requires a great deal of mouse movement and two window 
updates. Remember that updating the window can take a good 
amount of time (depending on the complexity of the 
document) To make this situation worse, the user has no 
visual confirmation of what might be at the bottom-right of 
the document. 

The other approach that you might be familiar with is the 
Show Page goodie in MacPaint. In this approach, a new 
window appears and a miniature version of the document is 
drawn. You can then move a rectangle around to show where 
you would like the window to be positioned. Then you hit 
the OK button or the Cancel button, the window goes away, 
and your document window reappears, showing the area you 
selected. This does overcome the need for a mental picture of 
the whole document. While this method only requires 
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Fig. 1 Getting the Big Picture... 

updating the window once, it has the unfortunate problem of 

introducing a new mode to the user. In Apple's Do's and 

Don'ts of a Friendly User Interface, over-using modes is the 

first Don't. 

The problem then is a matter of giving the user some idea 
of what the document looks like and permitting easy access to 
any part of the document. Other approaches have been 
implemented, many of which have contributed to the ideas that 
go into the solution given here. This solution not only 
solves the primary problem, but it draws from a number of 
elements of the Macintosh interface that are already very 
familiar, hence the name: The Pop-up, Two 
Dimensional, Random Access, Scroll Bar Menu, or 
simply, OverView. 

How OverView Behaves 

It behaves just as it is named. At the user's request 
(discussed later), something akin to a menu pops up. It has 
the proportions of the document and it contains a miniature 
picture of the document. The area currently showing in the 
document window is highlighted. As long as the user holds 
down the mouse button, a gray rectangle the same size as the 
highlighted area moves around with the cursor, showing the 
area that will be selected if the button is released. Like most 
Macintosh controls (e.g. the scroll bar thumb), if the cursor is 
moved too far away from the window, the gray rectangle 
disappears. If the mouse is released when the rectangle is 
gone, the Pop-up window disappears and nothing happens. If, 
on the other hand, the button is released while the gray 
rectangle is showing, the old selection dehighlights and the 
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new selection flashes in the same way that menu selections 
flash when selected. The scroll bars change appropriately, and 
the program gets notified that it needs to redraw the contents 
of the window at the new location via an update event. 

With OverView, the user never perceives a change in 
mode, yet has access to the whole document in one easy step. 
Like pull-down menus, OverView will not generate activate 
events. It will not create update events unless a new selection 
is made. It appears quickly and disappears quickly. While it 
may seem complicated after reading this description, try using 
it once. It is much easier used than described. 

Summoning OverView 

OverView was created to view large typeset pages at 
varying levels of magnification. As such, it was designed to 
be used in a passive mode. That is, the user could only view, 
not change the document contents. This has an important 
relationship to how OverView was first used. Since Clicking 
in the window pane (the area of the window where the actual 
document is, excluding controls) had no implicit meaning, 
that was used to activate OverView. However, in documents 
where text editing or object editing (e.g. MacWrite, MacDraw) 
takes place, clicking in the pane has other meanings. Another 
method of summoning OverView is called for. Andy 
Hertzfeld gets credit for the idea of putting an eyeball icon at 
the bottom-left of the window and scooting the horizontal 
scroll bar over to the right. Clicking on the eye could 
summon OverView. Another possibility is similar to the 
zoom box capability added in the new ROMs. The eyeball 
could be placed in the title bar between the close box and the 
title. Clicking on the eye would function almost exactly like 
a pull-down menu. 

Making the choice on this is left to you, the creative 
program designer, to see what users like best. Keep in mind 
that it gets tiresome having to move the cursor to an exact 
point on the screen to use a function, especially if you happen 
to spend a lot of time far away from that spot. That was the 
beauty of the very first approach, because it was always 
available whenever you were in the window of interest. A 
typical power-user trick could come in handy for non-passive 
windows. Perhaps Option- click or Command-click or 
Command-Option-click could be used (as in PageMaker™), 

Operational Details 

OverView has a few very special features. Some were 
mentioned above. Others are listed here. For example, the 
pop-up window always remains within the boundaries of the 
front window. This is important for the prevention of the 
generation of update events. OverView knows that the only 
window it will ever affect is the front window, so it can easily 
convince that window that it was not affected (see the code). 

OverView provides flexibility by taking advantage of the 
information available to it about the front window. By 
looking at the size of the window pane and comparing it to the 
size of the document, it scales the rectangles appropriately. It 
also takes advantage of the available screen size (just in case 
bigger screens just happen to come along). 

Every window which will have its own OverView Pop-up 
needs a WindowPt and a BitMap. NewOverView works by 
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creating a new window for the Pop-up window. It then creates 
an offscreen bitmap into which a miniature of the document 
can be drawn with UpdateOverView. Then, whenever it is 
summoned, OverViewSelect makes its window appear after 
saving the bits underneath it into a temporary bitmap. It 
shows the Pop-up window without deactivating the document 
window by using ShowHide and some trickery. It copies the 
offscreen bitmap miniature into the OverView window and 
calls TrackGrayRgn to get the user's selection. It then hides 
the window, restores the bits underneath the Pop-up window, 
and sets the scroll bars based on the new selection. 
The Interface 

The code is broken up into three procedures: 
InitOverView, UpdateOverView, and OverView— Select. The 
code is in the form of a Macintosh Workshop Pascal (MPW 
Pascal) Unit, which can be compiled separately and linked in 
just like any of the Toolbox Managers. For now, it is enough 
to know that MPW Pascal is essentially Lisa Pascal. 
OverView was initially written in TML Pascal as a straight 
program. The conversion to MPW Pascal took five minutes 
and was mostly changing the include files and compiler 
Switches. For more information, see the MPW Section 
below. 

NewOverView should be called once for every window that 
will have an OverView window. Pass in an empty bitmap, an 
empty window pointer, a rectangle with the size of the virtual 
document (origin at 0,0), and a size factor (a real number 
between 0 and 1). NewOverView creates a new window whose 
height is determined by the available screen height multiplied 
by the size factor. NewOverView creates an offscreen bitmap 
and fills in the BitMap's record. 

It is your program's responsibility to keep the miniature 
picture up to date. You can draw into it by passing your 
drawing procedure and the bitmap to UpdateOverView. It will 
not do any drawing or erasing. It simply sets things up to do 
the drawing, calls your drawing routine, and resets everything 
to normal before exiting. Thus, rather than erasing and 
redrawing the entire picture, you might just draw the parts that 
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have changed if that is less work or less time consuming. 

Whenever you decide to summon OverViewSelect, call it 
by passing in the point from the MouseDown event, the 
rectangle (origin at 0,0) with the dimensions of your virtual 
document, the point that corresponds to the upper-left corner 
of the viewing window (in terms of the size of the virtual 
document), the bitmap from NewOverView, and handles to the 
horizontal and vertical scroll bars. 

Beware that the viewing window should not be permitted 
to resize any smaller than the OverView pop-up window. The 
trick used for soaking up update events will not be reliable if 
the OverView window overlaps any other windows. Just be 
sure to set the pop-up window size as the smallest size 
allowed whenever growing a window. 

Changing the size of the virtual document is fine as long 
as the ratio of the sides remains the same. If that changes, the 
old window and bitmap should be disposed of and new ones 
allocated. 

Watch out! If you choose a Pop-up window size that is 
too large, CopyBits freaks out. This will lead to unpredictable 
behavior. The OverView code needs to be modified so that it 
never attempts to CopyBits any sections larger than 3K at a 
time. Unfortunately, deadline pressure prevented this fix. A 
factor of 0.5 works just fine on all currently available Mac- 
type hardware (except on the XL), but 0.6 is too much. The 
fix will certainly be available before the new hardware hits the 
market. The problem with the XL appeared just at press time, 
so it has not been tracked down yet. 

Understanding the OverView Code 

When you call OverViewSelect, a number of things 
happen. The window is positioned so it stays within the 
boundaries of the FrontWindow. Then, before actually 
displaying the window, the screen bits where it will appear are 
saved into an offscreen bitmap. The window appears, the 
miniature picture is blasted into the window, the relative size 
of the current selection is computed, the current viewing 
selection is highlighted, and the user is given an identically- 
sized gray rectangle to drag around, which is tracked until a 
MouseUp. If a selection is made, the old selection is 
dehighlighted and the new selection is flashed MenuFlash 
times. The window is hidden and the screen bits are copied 
back into place. If a selection was made, the scroll bars are set 
appropriately. | Otherwise, the update events for the 
FrontWindow are cleared. 

Note that the window position on the virtual document is 
stored in a scroll position variable as well as in the scroll bars 
themselves. Figure 1 shows the organization of the important 
variables and how they relate to each other. The position of 
the window on the document is directly related to the settings 
of the scroll bars. The size of the highlighted area and the 
draggable gray region are proportional to the size of the 
window pane relative to the document's overall size. Figure 2 
shows a picture document and should help you get a better feel 
for how everything looks. Please understand that the 
miniature picture as printed has much higher resolution than 
the screen (300 dots per inch versus 72 d.p.i.), so it looks 
much better on paper. In addition, the sharp reader will notice 
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that the eyeballs were not used to summon the OverView 
window in either Figure 1 or 2. They are shown to let you 
get the visual effect of the different placement. 

The code uses two offscreen bitmaps. The first stores the 
miniature picture. Create it with NewOverView before using 
any of the other OverView routines. Dispose of it when you 
are done with it. The second bitmap stores the bits underneath 
the pop-up window whenever it appears. It is allocated 
dynamically before showing the pop-up window and 
deallocated right after hiding the window. The Mac's menu 
manager works in a similar manner, allocating and 
deallocating on demand. 

The trick used to mask out update events relies on the 
following argument. OverViewSelect should not be called if 
there are outstanding update events for the front window. 
Update events must be handled prior to invoking 
OverViewSelect. Since we assume there will not be any 
update events for the front window, we can safely assume that 
any that are generated during the time that OverView is in use 
were generated by us. By doing a BeginUpdate and an 
EndUpdate for the FrontWindow, the update events are 
eliminated. This means that we must be sure to restore the 
bits that were underneath the OverView window since the 
window manager will not ask for the window to be updated. 
You should also consult Mike Schuster's C Workshop: Try 
Pop-Up Menus! (MacTutor, December 1985, pp.15-22) for 
an excellent discussion of handling bitmap allocation, 
rectangle placement, and other issues important to pop-ups. 

As always, an intimate knowledge of Inside Macintosh 
will aid you immensely in understanding the code. CopyBits, 
DragGrayRgn, the Window Manager, the Control Manager, 
MapRect, MapPt, and SetPortBits should provide some 
interesting reading topics for you. 

The Sample Program 

In addition to the OverView unit, this article includes a 
sample program to give you a feel for how you can include 
OverView in your own programs. The sample program brings 
up a window to fill the screen. It sets up scroll bars on the 
right and bottom, leaving room for the eyeball at the bottom- 
left corner. It then waits for a KeyDown event, which will 
exit the program, or a MouseDown event, which will 
summon the OverView window. 

The sample also has a menu for changing the size of the 
virtual document. The three sizes given are for a typeset 
8.5x11" page at screen resolution, ImageWriter resolution, and 
LaserWriter resolution. Once again, you can see the 
typesetting origin of OverView and its associated tools. 
Notice the differences when you change sizes. The pop-up 
window does not change its size, but the size of the selection 
rectangle inside it does change. For example, the selection 
rectangle is much smaller when LaserWriter resolution is 
selected than when screen resolution is selected. This is 
because the window pane shows a different portion of the 
overall document. 

A couple of general programming notes follow. First, 
note that the viewing window (the one that stays visible with 
the picture in it all the time) is sized to the full size of the 
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screen. Thus, if it runs on a Lisa, it takes full advantage of 
the screen size. And, if Apple decides to come out with larger 
Mac screens, no problem. With the simple technique in 
SetUpWindow, any program can be prepared to use all 
available screen space. If Apple decides to offer different 
screen resolutions, this program will not know about it. 
However, with some additional code, it could use the screen 
resolution globals to compute the pixel size of 
MenuBarHeight, TitleBarHeight, ScreenMargin, SBarHeight, 
and SBarWidth to keep them the same size that we are all used 
to 


Pascal units. Since OverView is in its own separately 
compiled unit, the sample only needs to include it and the 
programmer can safely forget about the details of OverView 
and instead treat it just like any other Mac manager. 

You might notice in the MacTutor article referenced earlier 
that his code does not use a window. Rather, he uses only an 
offscreen bitmap. While an OverView could be made in a like 
manner, this implementation uses: a window intentionally. It 
seemed more natural at the time, and still does. If you have 
comments on this approach, please send them. 

MPW -- What Is it? 

MPW stands for Macintosh Programmer's Workshop. It 
is the development environment many of us have been waiting 
for. Its power tools include a unix-like Shell, a 68xxx 
assembler, a linker, a debugger, a resource editor, and a 
resource compiler/decompiler. With the shell, you get an 
environment where you can edit, manipulate files, compile, 
link, and run programs in multiple windows. The shell offers 
integration, command scripting, regular expression processing, 
and extensibility. 

Macintosh Workshop Pascal, Macintosh Workshop C, and 
MacApp are available separately as MPW tools. The Pascal 
and C have migrated from the XL Workshop to a truly on-the- 
mac, for-the-mac environment. 

MPW runs on just about anything except the old 128K 
machines. It will be coming available on the market from 
Apple reportedly by the end of the year. No cost has been 
given, but guesses are in the $500 range, depending on 
whether you get Pascal, C, and/or MacApp. 

MacApp stands for the expandable Macintosh application. 
Finally, all of us who wondered why it was so hard just to put 
some text in a window will have a tool where you spend your 
time describing the differences between your application and 
the standard application. Things like windows, menus, 
updating, text editing, AppleTalk, filing, and all the ordinary 
things are taken care of automatically. MacApp is a 
revolutionary product you should pay careful attention to. It, 
too, will be coming available hopefully by year's end. 

Workshop Pascal and TML Pascal 

The simple, plain truth is, if you program in Pascal on the 
Mac, you are probably using TML Pascal. OverView was 
originally programmed with TML Pascal, as were all of my 
programs. At least, that is, until recently. If you want to use 
OverView with TML Pascal, read on. 

Workshop Pascal brings a number of good things to the 
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This sample shows some of the beauty of Workshop 


Mac that other Pascals just do not offer. Two in particular are 
Objects and Units. Objects allow you to program in an object 
oriented fashion. You are familiar with the objects used in the 
Mac interface: windows, menus, boxes, scroll bars, etc. With 
object programming, you can write your programs to treat 
objects as somewhat intelligent creatures with the ability to 
communicate with you. For a better description than space 
allows, consult the new book from Hayden Press, Object 
Oriented Programming for the Macintosh, by Kurt J. 
Schmucker. It is an excellent book, and one of the first to 
comprehensively address the issue of object programming. 

The other benefit of Workshop Pascal is Units. The 
toolbox managers you know and love were written as units. 
A unit is a separate chunk of code. OverView is a sample of 
Such a chunk. It consists of an interface part and an 
implementation part. The interface part declares constants, 
types, variables, and procedures that are available to the 
outside world. The implementation part has the actual 
working code, and can contain its own private constants, 
types, variables, and procedures. 

A unit stands alone by itself. It is compiled separately. 
When your program says uses identifier, the compiler goes 
out and reads in the interface part, treating the procedure 
declarations like Forward declarations. You then link in the 
separately compiled unit with your program in the link step, 
just like the toolbox interfaces. 

Now, what do you do if you have TML Pascal? No 
problem. Include the text of OverView.p directly in your 
program. Remove the words UNIT OverView, INTERFACE 
and IMPLEMENTATION and the final END. Remove the 
compiler switch settings. In the interface section, add 
FORWARD; at the end of the three procedures. Modify the 
uses clause to the TML equivalent. Put the interface section 
into the front of your program. Put the implementation 
section anywhere in your program. 

According to a TML spokesperson, the Object Pascal 
extensions and separate unit compilation will be in TML 
Pascal Version 2.0, expected some time before you read this! 
Tom has added some staff and seems to moving right along. 
If you have 2.0, you should not need to make any changes 
other than the compiler directives and the Uses clause. 

Summary 

This addition to the Mac interface has caught on here in 
Aggieland. Several people have commented that the idea Was 
so natural that they had tried (in vain) to summon OverView 
while they were using MacDraw and MacPaint! If you find a 
good way to add an OverView capability to Draw or Paint, 
please let me know. My only solution right now involves 
FKEYs and searching the heap for windows and scroll bars, 
and it looks highly involved. Please use this code in your 
own programs if you like the way it feels. 

Until the Mac has the hardware capability to zoom in and 
out on a document (like the Symbolics 3600), this kind of 
tool will give the rest of us some ability to get the big 
picture and feel in control of our large documents. 

UNIT OverVies; 


(Version 1.8 Saturday, July 12, 1986 9:47:53 PM by Scott T. 
Boyd of the MacHax™ Group. 
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Many thanks to Greg Marriott of SoftWare To Go, also a member 
of the MacHax™ Group 


INTERFACE 


(Compiler Switch Settings) 
($n) 

($0v4) 

uses MemTypes, QuickDraw, OSIntf, ToolIntf, SANE; 
cons 


MenuBarHeight= 28; 
TitleBarHeight = 18; 
= 4: 


(Height menu bar in pixels) 
{Height of title bar in pixels) 


ScreenMargin : (Width of "safety margin" } 
SBarHeight = 15; (Height of scroll bar) 
SBarWidth = 15; (Width of scroll bar) 


Procedure NewOverView( var OV.pagePict : bitMap; 

var OV : WindowPtr; viewRect : Rect; factor : Real ); 
Procedure UpdateOverViewC 

Procedure drawProc; OV .pagePict : bitMap); 
Procedure OverViewSelect( where: Point; viewRect : Rect; 

VAR scrollPosition : Point; VAR OV : WindowPtr; 

VAR OV_pagePict : bitMap; 

HScrollBer,VScrollBar : ControlHandle); 


IMPLEMENTATION 


Procedure NewOverView (( var OV.pagePict : bitMap; 
ver OV : WindowPtr; viewRect : Rect; factor : Real 2); 


var 
dummyRect: Rect; 
horizontal, (horiz. pixel size of OverView } 
vertical: Extended; (vert. pixel size 
sizeOfOff: Size; (bytes for offscreen bitmap) 
of fRowBytes: Integer; (row bytes for offscreen bitmap) 
bitRect: Rect; (size of OV window, bitmap) 
dummy: Point; 
offPort, (temporary working port) 
oldPort: GrafPtr; (temporary storage) 


begin (compute available vertical screen space) 

vertical := ScreenBits.bounds.bottom- ScreenBits. bounds. top- 
MenuBarHe ight; 

vertical := vertical * factor; 

{compute horizontal to proportion} 

horizontal := vertical * viewRect.right / viewRect.bottom; 

(create the new window record) 

SetRectCdumnyRect, 9, Ø, Num2IntegerChorizontal), 
Nun2Integer(vertical)); 

OV := NewWindow€ nil, dummyRect, '', FALSE, altDBoxProc, 
WindowPtr(-1), FALSE, LongInt(0) ); 

(create offscreen bitmap} 

bitRect := 0V^.portRect; 

offRowBytes := ((bitRect.right-bitRect. left) div 8) + 1; 

if OddC offRowBytes ) then 

offRowBytes := offRowBytes - 1; 
sizeOfOff := (bitRect.bottom-bitRect.top) * offRowBytes; 
with OV.pagePict do 


begin 
baseAddr := QDPtr( NewPtr( sizeOfOff )); 
rowBytes := of fRowBytes; 
bounds  := bitRect; 

end; 


(fill the bitmap with white) 
GetPortC oldPort ); 
offPort := GrafPtrC NewPtrC sizeofC GrafPort ))); 
OpenPortC offPort 2; 
SetPortBitsC OV.pagePict 2; 
FillRectC bitRect, white 2; 
SetPortC oldPort ); 
ClosePort( offPort 2; 
DisposPtrC PtrC offPort 2); 
end;  (MakeOverView) 


Procedure UpdateOverView (€ drawProc : Procedure; 
OV_pagePict : bitMap)); 
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ver 
offPort, 
oldPort: 
begin 
GetPort( oldPort ); 
offPort := GrafPtr( NewPtrC sizeofC GrafPort 22); 
OpenPort( offPort ); 
SetPortBits€ OV_pagePict 2; 
drawProc; 
SetPortC oldPort ); 
ClosePort( offPort 2; 
DisposPtrC PtrC offPort 22; 
end; (UpdateOverView) 


Procedure OverViewSelect(( where: Point; 
viewRect : Rect; VAR scrollPosition : Point; 
VAR OV : WindowPtr; VAR OV_pagePict : bitMep; 
HScrollBar,VScrollBer : ControlHandle)); 


GrafPtr; 


(make drawing offscreen} 
(let the user drew) 
(return drawing to normal) 


ver 
MenuFlash : “Integer; (system global) 
value, (value returned by TrackGrayRgn} 
h, v: LongInt; ) 
pane, 
tempPt: Point; 
Scope, (size of window pane scaled into OV window) 
tempRect, 
limitRect, (limit for drag region) 
slopRect: Rect; (slopiness allowance for dragging) 
dragRectRgn: RgnHandle; (the region the user drags 
oldPort: — GrefPtr; 
theW indow WindowPtr; (holds frontWindow) 
underScope: BitMap; (offscreen bitmap) 
whichWindow : WindowPtr; (for save and restore bits) 
Procedure OV_Prepare; 


MenuF lash := pointer($A24); 
GetPortC oldPort ); 
theWindow := FrontWindow; 
BringToFront(C OV 2; 


(the active window ) 

(make OV appear, but not really) 
SetPort( OV ); (it's now the current port) 
ShowHideC OV, FALSE 2; (it's also not visible) 
MoveWindowC 0V,0,0,FALSE 2; (home the window) 


(compute the size of the current window pane) 

pene.h := theWindow^.portRect.right - 
theWindow^.portRect.left - sBarWidth; 

pane.v := theWindow^.portRect.bottom - 
theWindow^.portRect.top - sBerHeight; 


(scale the pane into the OV window to show size ) 
SetRect( tempRect, Ø, Ø, pane.h, pane.v ); 
MapRect( tempRect, viewRect, OV^.portRect ); 
Scope := tempRect; 
(make the region to drag around. 
dragRectRgn := NewRgn; 
RectRgnC dragRectRgn,scope ); 
(this works to limit the movement of dragRectRgn} 
SetRectC limitRect, Ø, Ø, OV*.portRect.right- 
scope.right*1, 
OV* .portRect.bottom-scope.bottom*1 2; 
(scele scrollPosition into OV for placing scope in OV) 
tempPt := scrollPosition; 
MapPtC tempPt, viewRect, OV^.portRect 2; 
OffSetRect( scope, tempPt.h, tempPt.v ); 


seme size as scope) 


end; (0V.Prepere) 


Procedure OV.PositionOverView; 
var offset : Point; 


gin 
SetPortC oldPort 2; 
offset := where; 
GlobalToLocal C offset ); 
h := offset.h; (local value of mousedown) 
v := offset.v; 
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(make sure it doesn't go off the bottom of the window} 
if Cv + OV*.portRect bottom) >= 
theWindow^ .portRect .bottom 
then v := theWindow^.portRect.bottom - 
0V^.portRect.bottom - 1; 
(make sure it doesn't go off the right of the window) 
if Ch + OV*.portRect.right) >= 
theWindow* .portRect .right 
then h := theWindow^.portRect.right - 
0V*.portRect.right - 1; 
(make sure it doesn't go off the top of the window) 
if v < theWindow^.portRect.top then v := 
theWindow^.portRect.top; 
{make sure it doesn't go off the left of the window) 
if h < theWindow*.portRect.left then h :- 
theWindow* .portRect. left; 


SetPt ( offset, h, v); 
LocalToGlobalC offset ); 
h := offset.h; 

offset.v; 


" ee 


V 


SetPortC OV ); 
MoveWindowC OV, h, v, FALSE ); 
end; {OV_PositionOverView) 


procedure OV_SaveBits; 
var 


sizeOfOff: Size; 

of fRowBytes: Integer; 

underRect, 

bitRect : Rect; 

dummy Point; 

offPort, 

oldPort : GrafPtr; 
begin 


GetPortC oldPort ); 

(put window magager port into offport as a windowptr) 
GetWMgrPortC offPort ); 

whichWindow := WindowPtr( offPort ); 

{allocate a new grafport) 

offPort := GrafPtr( NewPtr( sizeof( GrafPort 225; 
(home a copy of the bounds of the OV window) 

bitRect := OV*.portBits.bounds; 

offsetRect( bitRect, ~bitrect. left, -bitrect.top ); 
(compute memory necessary for offscreen bitmap} 
(allocate it and setup bitmap record) 

offRowBytes := ( bitRect.right div 8 ) + I 

if Odd offRowBytes ) then offRowBytes := offRowBytes - 


sizeOfOff :- bitRect.bottom * of fRowBytes; 
with underScope do 


begin 
baseAddr := QDPtr( NewPtr( sizeOfOff )); 
rowbytes := of fRowBytes; 
bounds := bitRect; (using HOMEd rectangle) 
end; 


(nove a copy back where OV will appear} 
underRect := underScope.bounds; 
OffsetRectC underRect, h-1, v-1 ); 
(actually save the bits) 
OpenPort(C offPort ); 
SetPortBits( underScope ); 
SetClipC offPort^.visRgn ); 
CopyB i tsC whichWindow^.portBits, underScope, 

underRect, underScope.bounds, srcCopy, NIL); 
SetPortC oldPort ); 
ClosePort( offPort ); 
DisposPtr( PtrC offPort )); 

end; (0V_SaveBits)}) 


Procedure OV_ShowOverView; 
var 


boxWidth, 
boxHeight: integer; 
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begin 
OV_SaveBits; 
ShowHideC OV, TRUE ); (now window appears) 
(blast miniature picture into OV) 
CopyBi tsCOV. pageP ict, OV* .portBits, 
0V. pageP ict bounds, 0V* .portRect,srcCopy,ni 12; 
(highlight the current selection) 
InvertRect( scope ); 
(give the user some room to be sloppy) 
SlopRect := 0V^.portRect; 
InsetRect( slopRect, -25, -25 ); 
GlobalToLocalC where ); 
(compute size of draggable region and center it } 
boxWidth := scope.right - scope. left; 
boxHeight := scope.bottom - scope. top; 
OffsetRgnC dragRectRgn, where.h-(boxWidth div 2), 
where.v-CboxHeight div 2) ); 
OffSetRectC limitRect, boxWidth div 2, boxHeight div 2); 
(let the user drag it around) 
value :- DragGrayRgn( dragRectRgn, where, limitRect, 
SlopRect,@,nil ); 


end; (0V.ShowOverView) 


Procedure OV_RestoreBits; 

var underRect: Rect; 

begin 
underRect := underScope . bounds; 
(home the rectangle) 
OffsetRectCunderRect, -underRect. left, -underRect. top); 
(position it correctly) 
OffSetRectC underRect, h-1, v-1); 
(blast stuff under window back into position) 
CopyBitsC underScope, whichWindow^.portBits, 

underScope .bounds, underRect,srcCopy, NIL); 

(deallocate the bitmap space (be nice and clean)) 
DisposPtr( Ptr( underScope.baseAddr 25; 

end; (0V RestoreBits) 

( 


Procedure OV. HandleSelection; 
Procedure OV_FlashSelection; 
var i: Integer; 
j: LongInt; 
begin 
HLockC HendleC dragRectRgn )); 
for i 


(good habit!) 
:* ] to 2*MenuFlash^ do begin 

InvertRect( dragRectRgn^^.rgnBBox ); 

delayC 4,j ); 

end; 


HUnLockC Handle dragRectRgn )); (yep!) 


begin (0V HandleSelection) 
if CHiWord(value)<>-32768) or CLoWord(value)<>-32768) 


then (user actually made a selection) 
begin 
InvertRect( scope 2); (turn off current selection) 
OV FlashSelection; 


ShowHideC OV, FALSE ); 
SetPortC oldPort ); 
OV_RestoreBits; 


{hide the OV window} 
(blast bits back into place} 


(figure the new scrollPosition based on the top-left corner) 
(of the draggable region) 
SetPt( tempPt, 
dregRectRgn^^.rgnBBox.top ); 
MapPtC tempPt, OV^.portRect, viewRect ); 
scrollPosition := tempPt; 
tempRect := viewRect; 
tempRect bottom := tempRect.bottom - pane.v; 
tempRect.right := tempRect.right - pane .h; 
MapPt € tempPt, tempRect, viewRect ); 
(set the new scroll bar values) 
SetCtlValueC HScrollBar, tempPt.h ); 
SetCtlValueC VScrollBar, tempPt.v ); 


dragRectRgn** .rgnBBox. left, 
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InvalRect( theWindow^.portRect ); 
end 
else (no selection was made) 
begin 
ShowHide( OV, FALSE ); 
SetPortC oldPort ); 
OV_RestoreBits; (replace underneath bits) 
BeginUpdate( theWindow ); 
(steal update events) 
EndUpdate ( theWindow ); 


(hide window) 


end; 
end; (0V.HandleSelection) 


in 
DisposeRgn( dragRectRgn ); 
ris (0V. T idyUp) 


begin 
OV. Prepare; 
0V-PositionOverView; 
OV. ShowOverView; 
0V HendleSelection; 
OV_TidyUp; 
end; (OverViesSelect) 
END. (UNIT OverView) 


program OverView Sample; 
(OverView Sample 

Version 1.8 Scott T. Boyd 
Monday, July 14, 1986 3:32:08 AM ) 


oe iler Switch Settings) 
R+) (range checking on} 
ae (overflow checking on) 


uses MemTypes, QuickDraw, OSIntf, ToolIntf, ($U OverView.p) 
OverView; 


const 

AppleID = 1; (Menu ID for Apple menu) 

AboutItem = 1; (Item number for About... command) 
FileID = 2; (Menu ID for File menu} 


QuitItem = |; (Item number for Quit command) 


EditID = 3; (Menu ID for Edit menu) 
Undoltem = 1; (Item number for Undo command) 
CutItem = 3; (Item number for Cut command) 
CopyItem = 4; (Item number for Copy command) 
PasteItem = 5; (Item number for Paste command} 
ClearItem = 6; (Item number for Clear command) 

ViewID = 4; (Menu ID for for View menu) 

ScreenItem = 1; (Item for Screen res command) 
Imageltem = 2; (Item for 2 times magnify view cmd} 
LaserItem = 3; (Item for 4 times magnify view cmd) 

App leMenu : MenuHandle; 

FileMenu : MenuHandle; 

Edi tMenu : MenuHendle; 

ViewMenu : MenuHandle; 


type modes = (screen, image, laser); 


var 
MScope, (for the OverView window record) 


TheWindow : windowP tr ; (fordocument view window) 
OldPort : GrefPtr; (to keep things tidy) 
TheEvent : EventRecord; 
LaserViewRect, (the different document sizes) 
InageV iewRect, (the different document sizes) 
ScreenV iewRect, (the different document sizes) 
viewRect  : Rect; (the most current size) 
viewmode  : modes; (the most current mode) 
myBitMep : BitMap; (OverView offscreen minipict) 
var 
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VScrollBer, (Handle to vert scroll bar) 
HScrollBer : ControlHandle; (Handle to hor scroll bar) 
scrollPosition : Point; (Current scroll position) 


procedure SetUpWM indow; 
( = TheWindow, the "viewing" window that stays up all the 
time 


P OM Rect : Rect; 
begin ts Se tUpWindow} 

with ScreenBits.bounds do (use all avail screen space) 

begin 
dummyRect . top = 
top*MenuBarHe ight+ScreenMargin+TitleBarHeight; 
dummyRect . left lef t*ScreenMargin; 
dummyRect .bottom bottom-ScreenMargin; 
dummyRect .right right-ScreenMargin; 
end; 

TheWindow := NewWindow (nil, dummyRect, ‘PopUp 2D Random 
Access Scroll Bar Menu’, true, NoGrowDocProc, WindowPtr(-1), 
true, longint(0)); 

SelectWindowCTheWindow); 

SetPortCTheWindow); 
end; (Se tUpW indow) 


procedure SetUpControls; 
{Create and initialize TheWindow's verti and hor scroll bars } 


en 
VScrollRect, HScrollRect : Rect; 
begin (SetUpControls) 
with TheWindow^.portRect do 


SetRectC VScrollRect, right-15, top-1, right*1, bottom- 14); 


with TheWindow^.portRect do 

SetRect( HScrollRect, left*15, bottom-15, right-14, 
bottom+! ); 

VScrollBar := NewControlC(TheWindow, VScrollRect, '', TRUE, 
P, 0, viewRect .botton, ScrollBarProc, Longint(@)); 
.. HScrollBar := NewControlCTheWindow, HScrollRect, '', TRUE, 
9, 0, viewRect.right,ScrollBarProc, Longint(@)); 
end; (SetUpControls) 


oo" SetUpMenus; 


St ioni Str ingL 1); 
begin (SetUp Menus) 
eppleTitle := ' '; 
eppleTitle[1] := chr Capp leMark); 
eee := NewMenuCAppleID, appleTitle);(Create Apple 
menu 
AppendMenu( App ]eMenu, ew D Just for looks..;(-'); 
AddResMenuCAppleMenu, ‘DRVR'); (Add desk acc) 
InsertMenuCAppleMenu, 8); ' (Install at end ber) 
FileMenu := NewMenuCF ileID, 'File'); (create File menu) 
InsertMenu(CF i leMenu, Ø); (Insta11 at end of ber) 
AppendMenu(F i leMenu, ‘Quit’ ); 
EditMenu := NewMenu(EditID, ‘Edit'); (create Edit menu) 
InsertMenuCEditMenu, 9); (Install at end of bar) 
AppendMenu(EditMenu, ' Undo; (-;Cut; ; Copy; Paste; Clear’); 
ViewMenu := NewMenuCV iewID, ‘Document Size’); 
InsertMenu(ViewMenu, Ø); {Install at end of menu bar) 
AppendMenuCV iewMenu, ‘Screen Resolution’); 
AppendMenu(CV iewMenu, ' ImageWriter Resolution’); 
AppendMenu(CV iewMenu, ‘LaserWriter Resolution’); 


DrawMenuBér ; 
end; (SetUpMenus) 


© The Complete MacTutor, Vol. 2 


(Show new menu bar on screen} 


procedure DoViewChoiceCtheltem: INTEGER); 

( Handle a selection from the Document Size menu ) 

( i It's a bit of work to support multiple document 
Sizes! 


ver 

paneSize : 
begin 

case theltem of (select the new virtual document size} 


Point; 


ScreenItem: viewRect := ScreenViewRect; 
ImageItem:  viewRect := imageViewRect; 
LaserItem: view t := laserViewRect; 


end; (case) 


CheckItem(ViewMenu, ScreenItem, false); (turn off the 
checkmarks) 
CheckItem(ViewMenu, ImageItem, false); 
brute force method 
CheckItemC(ViewMenu, LaserItem, false); 
CheckItem(ViewMenu, theItem, true); ( checkmark) 
(Reset the scroll bars for the new rectangle size) 
paneSize.h:=TheWindow* .portrect.right - 
TheWindow* .portrect.left - SBarWidth; 
paneS ize. v:-TheWindow^.portrect.bottom - 
TheWindow^.portrect.top - SBarHe ight ; 
SetPt(ScrollPosition,2,0); 
SetCtlValueCVScrollBar, 2); 
SetCtlValueCHScro11Bar, 2); 
SetCtMaxCVScrolBer, viewRect.bottom - paneSize.v); 
if viewRect.right < paneSize.h (Lisa's wide screen] 
then — SetCtlMaxCHScrollBar,2) (can't scroll if it shows) 
else SetCtlMaxCHScro!1Bar, viewRect.right - paneSize.h); 


(definitely a 


ShowControl(VScro11Bar); 

ShowControlCHScro11Bar); 

DrawControlsCTheWindow); 

HiliteControl(VScrollBar, 0); 

HiliteControlCHScrollBer, Ø); 
end; ( DoViewChoice) 


(estos sees eek eo es a ee ee 

procedure DoMenuCl ick; 

( Handle mouse-down event in menu bar. ) 

var 
menuChoice : LONGINT; (Menu ID and item number) 
theMenu : INTEGER; (Menu ID of selected menu) 
theItem : INTEGER; (Item number of selected item) 


begin  (DoMenuClick) 
menuChoice := MenuSelect(TheEvent .where);(Track mouse) 
if menuChoice <> Ø then (Nothing to do if Ø) 
begin 
theMenu := HiWord(menuChoice); (Get menu ID) 
theItem := LoWordCmenuChoice); (Get item) 
cese theMenu of 
AppleID: (DoAppleChoiceCtheItem)); 
FileID: if theItem = QuitItem then 
ExitToShel1; 

EditID:  (DoEditChoiceCtheItem)); 

ViewID: DoViewChoiceCtheItem); (only menu) 
end; 
HiliteMenu(£); 

menu title) 
end; (if MenuChoice) 
end; (DoMenuClick) 


(Unhighlight 


procedure DoMouseDown; 
{ Handle mouse-down event. ) 
var 
whichWindow : WindowPtr; (Window mouse pressed in) 
thePart : INTEGER; (Part of screen ) 
begin  (DoMouseDown) 
Where on the screen was mouse pressed?) 
thePart := FindWindowCTheEvent . where, whichWindow); 
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case thePart of 


InDesk: (Do nothing); 
InMenuBar : DoMenuC1 ick; 
InSysWindow: (Do nothing); 
InContent : OverViewSelect( 


TheEvent .where, viewRect, scrollPosition, 
MScope, myB i tMap , HScro11Bar , VScro11Bar); 


InDrag: (Do nothing); 
InGrow: (Do nothing); 
InGoAway: if TrackGoAway(TheWindow, TheEvent.where) 


then ExitToShell; 
end; (case) 
end;  {DoMouseDown) 


begin (nain) 
InitGref CéThePort); 
InitFonts; 
InitWindows; 
InitMenus; 
TEInit; 
InitDialogsC NIL ); 
InitCursor; 


{obligatory material goes here) 


SetRect ( LaserViewRect, 9, 0, 2549, 3299 ); 
SetRect ( ImageViewRect, Ø, Ø, 1274, 1649 ); 
SetRect ( ScreenViewRect, 8, Ø, 636, 824 ); 
SetPt C scrollPosition, 8, Ø ); 


SetUpMenus; 


viewmode := screen; 
CheckItem(ViewMenu, ScreenItem, true); (turn on the 
checkmark) 
case viewmode of 
Screen: viewRect := screenViewRect; 
image : viewRect := inageViewRect; 
laser : viewRect := laserViewRect; 
end; 


(SetUpControls is dependent on ViewRect being def ined) 
SetUpWindow; 
SetUpControls; 


(Create a window for TheWindow. Make it 1/2 the available 
screen height. Use myBitMap as the BitMap record, and 
point to the new window with MScope) 


NewOverViewC myBitMap, MScope, viewRect, 8.5 ); 
(Drew into the offscreen bitmap with DrawPoop) 
UpdateOverView C DrawPoop, myBitMap ); 


repeat 
if GetNextEvent(EveryEvent, TheEvent) then 
case TheEvent.what of 


MouseDown: DoMouseDown; 
KeyDown: (Do nothing); 
UpdateEvt: (Do nothing); 


ActivateEvt: (Do nothing); 
otherwise (Do nothing); 
end (case) 
until TheEvent.what = KeyDown; (quit if key pressed) 


Intermediate Mac ing 


Debugging with LightSpeed Pascal 


The Boston Expo this week promises to offer a world of 
new Mac products of particular interest to developers. Many of 
these products will revolutionize how software is done on the 
Mac, so it is time to take stock and review the software 
development process on the Mac. 

Where to Begin 

The first step in the product development cycle is to get 
information. This means getting a copy of Inside Macintosh 
by Addison Wesley, volumes 1-3 and soon volume 4. I prefer 
the hard bound all in one edition (great for dropping on 
bugs...). Next some Mac hardware is in order. A Mac Plus 
with a two meg upgrade from MacMemory is a must. A hard 
disk, scsi type, is helpful. The DataFrame 20 has been 
reported as a "safe" buy, reliable, few problems. À new round 
of 60 to 100 meg drives is also appearing in the $2500 range. 
Hardware and book in hand, it's time to reach for the check 
book and buy additional information. Apples software 
supplements and technical notes are a must, from Apple's 
mailing facility. For referencing the ROM, there is TOM's 
Program's little ROM reference deck. Finally, don't forget the 
MacTutor subscription! 

Utilities are important. No programmer should be without 
Fedit Plus, Mac Nosy 2.1, TMON or Heap Show. Both Fedit 
Plus and Mac Nosy 2.1 are new versions being shown at 
Boston. All four of these products are available from 
MacTutor as well as other technical software outlets. Heap 
Show is a very valuable little utility that allows you to 
analyze heap use in your program, find dangling handles and 
pointers, and help you prevent heap fragmentation. It is one of 
the most valuable of utilities yet is also the least known. 

Now loaded with documentation from IM, supplements 
and back issues of MacTutor, the next step is finding out what 
it all means. For this, the only way to go is to sign up for 
Dave Wilson's Macintosh Programming Class. This 
is Apple's official introduction to Mac Programming and it is 
indispensible. I just finished the class and I really learned a lot 
about the Mac that I either didn't know or didn't understand 
correctly. Dave is a master teacher and well versed in the Mac 
hacker's world. Cost is not cheap at $1,000, but it's well 
worth the price if your part of a company project. Six months 
after you're well along in development, thanks to Dave 
Wilson, you can then sign up for Scott Kanasters Mac 
College to get the bugs out of your project. But we're getting 
ahead of ourselves. First you must decide on a development 
system. 

HFS Changes Development Environment 

Under MFS, the Mac supported a number of traditional 
development systems. The Aztec C 1.06G is preferred by Unix 
programmers because it preserves much of the Unix flavor of 
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Fig. 1 The Many Windows of LightSpeed Pascal 


software development within the Mac interface. Consulair C 
and TML Pascal both present a similar Mac User Interface for 
software development using the traditional Edit/Compile/Link 
process. Under MFS, this traditional approach worked fine. 
However, under HFS, this approach breaks down because 
development systems must devise various methods of finding 
include files and trap files now arranged in different directories. 
The real problem is that HFS really makes the traditional 
approach of edit, compile and link obsolete. It simply takes 
too much time to run a program, bomb a program, debug a 
program, edit, compile, link and try again, when dealing with 
such a highly interactive and dynamic environment as 
Macintosh. Servant may ease this problem when available, by 
bringing a user configurable integrated environment to seperate 
programs not originally designed to be integrated, making a 
kind of user constructable LightSpeed environment, with the 
added advantage that you select the tools to install. 
Solving the HFS Problem 

The new world of development systems now coming out 
for the Mac solve the HFS problem by creating a development 
environment, in which all the files necessary to support the 
program development cycle is known to the system. These 
new systems are MPW from Apple, which brings Object 
Pascal and MacApp in a strong Unix style environment with 
scripts; TML Pascal 2.0, which also supports Object Pascal 
and units; and the newest product, LightSpeed C & Pascal, 
which create a "Project" that bundles files together 
dramatically speeding up compile and link. Let's focus on 
LightSpeed Pascal as this product typlifies the new 
"environment" approach that the Mac interface encourages. 

integrated Tools Speeds Debugging 

Mac programming is primarily a process of "discovering" 
what the Mac ROMS will let you do and how they let you do 
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it. Because of this, re-running programs over and over to 
experiment is a primary debugging task. With traditional edit, 
compile and link systems, this process takes several minutes. 
Make five change and test cycles and you've used up the better 
part of an hour! With the concept of a "Project", all files are 
loaded and available, compilation is virtually instant as only 
the necessary compilation is done, everything else is pre- 
compiled. Finally, linking is automatic since the project 
knows both what to link, and what needs to be re-linked after a 
change. The editing and executing environment are the same, 
So you can both edit, and execute your program from the same 
Shell, switching back and forth with a click of the mouse 
between your program's window and menus, and LightSpeed 
Pascal's windows and menus. Source is always available for 
editing and source code debugging is fully supported. The 
result is faster turn-around time in the edit, compile, execute, 
bomb, re-edit cycle. Instead of several minutes, new attempts 
are created and tested in seconds. An interactive environment 
that produces fully compiled double-clickable applications, 
DA's and drivers. 
How it works 

The key to LightSpeed Pascal is the project concept. A 
project is a window and a file that contains a list of all 
filenames associated with a particular program effort. It also 
contains compiler and linker information that allows only 
changed code to be re-compiled and linked dynamically. Since 
libraries and include files don't have to be re-loaded and 
compiled as they do on traditional systems, the project 
approach makes fast turn-around of the compile and link 
process. 

We write a program within our project environment with 
the LightSpeed Pascal "system". This system includes a multi- 
file editor. Our editing window is always available, even while 
our program is running. A build command creates a final 
application for us that is a fully compiled stand alone program 
we can move to any disk. For MDS ".REL" files, we can 
convert them to our project library format with a converter 
utility, provided. The compiler is fully Lisa and TML Pascal 
compatible. We compiled last month's keyboard sleuth 
program without any problem. The system does not have an 
assembler, so assembly code still must be assembled using 
MDS or Consulair C systems, and then converted for loading 
into our project. 

The Debugging Process 

If your frustrated at trying to marry your development 
system with MacsBug and TMON, then you'll really 
appreciate the LightsBug debugging window. Debugging is 
the key to this system. The system automatically debugs your 
Source code as you type, checking for syntax errors on entry. 
Instant compilation checks again for normal compilation 
errors. Finally, running the program again checks for run-time 
errors. At any time, if an error occurs, you can change the 
source, look at the debugger window, try some parameter 
values in the observe window, or change variable values in the 
instant window. To see what your program is doing, modify 
the source, set breakpoints and run again. Watch your window 
while you also watch the debug window! The debug window is 
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automatically linked to the point where your program stopped, 
Showing the heap trail, register values and your global 
variables. A single click on a global variable, and bang! The 
debugger shows you a hex and ascii memory dump at the 
location of the variable. 

Figure 1 shows the many windows of LightSpeed Pascal. 
Our own program window is also available! The project 
window lists our library, source and include files. Compiler 
options are set for each file by clicking in the box next to the 
file name. We change the link order for our project by simply 
dragging the file name up or down in the project window. No 
more editing of a link file! 

Our source code is shown in another window, and we can 
open a window for each of our source segments. The observe 
window allows us to monitor the value of a variable as our 
program executes. The Instant window allows us to execute 
program source code or trap calls instantly to observe their 
effects. If we get what we want, we can paste the line into our 
source window. Text and drawing have the same purpose they 
did under MacPascal, but even more important, our own 
toolbox created windows from our running program are 
available and clickable along with each of the other windows 
shown in figure 1. 
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procedure SayHi; 
var 

s :Str255; 

ia 


beg 
s := Hello there! This ts ye 
s = concat(s, chr(13)); 
putstring(s); 

end; 


procedure DoMyStuff; 
var 
s :str255; 


EN be oe ge) 

000: 3848 656C 6C6F 2074 6865 7265 :Hello there 
OOC: 2120 $468 6973 2069 7320 796F ! This is yo 
018: 7372 2066 726 


656E 646C 7920 
024: 4061 632E 2054 7970 6520 736F Mac. Type so 


Fig. 2 The Observe Window Shows value of s at break 
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procedure SayHi; 
var 
s : Str255; 
ia 


s := Helle there! This is ye 
s = concat(s, chv(13)); 
putstring(s); 


2034 7970 6520 736F "oc. Type 


tant Window changes s now! 


Fig. 3 The 
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In figure 2, we see how the observe window works. Here, 
we've placed a breakpoint at the putstring(s) statement in the 
source window. After running, our program is now stopped at 
the break, and the value of s is shown in bold in the observe 
window. Note that in the LightsBug window, we instantly 
have the base address of the variable s and can observe it's 
value in both hex and ascii. 

In figure 3, we now change the value of s in the instant 
window. As we do this, the observe window shows the new 
value of S, and the LightsBug window shows the new hex and 
ascii values for s in memory. 
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procedure SayHi; -a T 
var 


s : Str233, 


ia 
Pe Hello there! This is vem Smet © Mac. Type 
s = concat(s, ehr(13)); 
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Toggles Pascal 
to our window... 


Fig. 6 Changed memory shows in running 
program's window. 


In figure 5, we now wish to change the value that is 
assigned to s directly in memory where our source code lives. 
We do this by clicking edit and another little debug dialog box 
opens allowing us to enter a new value directly into memory. 
As we do this, the LightsBug window shows that what used to 
be "there!" is now "fere!". This also changes our source code 
and when we run the program, as figure 6 shows, the new 
source code value is shown being assigned to s during 
execution. 

Figure 7 shows that our program window exists along 
with LightSpeed Pascal's windows and we can swtich back and 
forth by clicking on the spray can (for debugging!). 

Finally a Decent Manual 

For some reason, Mac development systems have shipped 
with manuals that assume you already know every language 
command by heart. Very few even have a simple language 
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Fig. 7 Our Program window running... 


definition. If you don't already know C or Pascal, forget it! 
The LightSpeed manuals are very well done, very large and 
provide a clear description of the language syntax and 
commands much like normal manuals on other computers 
have traditionally done. It is a mystery to me why it has taken 
this long for decent manuals to be shipped with Mac 
development environments. 


More Details 

There are probably many other things we have forgotten. 
Did I mention single stepping while observing your program 
executing? According to the press releases, LightSpeed Pascal 
produces tight executable native code. There is some overhead 
associated with drivers as mentioned in the Networking article. 
Segments and units are fully supported and actually work for 
you since individual segments can be pre-compiled by the 
system and hence speeds up compilation and linking of the 
module your currently working on. All tooblox and OS traps 
are supported and assuming the product is similar to the C 
product, both desk accessories, code resources and drivers can 
be created, which includes just about everything. User 
generated resource files are supported with RMaker. Additional 
LightsBug features are heap tracing, called zones in 
LightSpeed Pascal and C, and chaining of subroutine names 
and activation order for tracing program execution. The heap 
display is a kind of mini-MacsBug showing handles, pointers, 
relocatable blocks and so forth. Won't replace TMON, but 

more than adequate for on-the-fly debugging. 

Reaction 

I personally think these products will revolutionize how 
software is done on the Mac. The time saved in testing and re- 
running programs under development is so tremendous that no 
one will settle for the large development time required of 
traditional edit, compile, and link systems. The Mac takes 
more time anyway in the learning curve of the ROM 
functions, so anything we can gain in the development cycle 
is extremely important. But most of all, LightSpeed Pascal 
will be very popular because no one will want to live without 
source level debugging with LightsBug if they don't have to. 
The debugging capabilities will cause people to stop and think 
if they really need all the overhead of MPW after all. Dd! 


Sato 
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Pascal Procedures 
Window Definition Routines 


In my first article describing definition routines, I stated 
that the best way to create a Definition Routine was to 
develop the routine as a procedure or function in your code, 
and when it is finished, make it into its respective resource 
(MDEF, WDEF, CDEF, LDEF). This finished resource can 
then be installed into your application and used just as you 
would a standard Definition Routine. There seems to be some 
confusion about this. 

Creating the routine within your program requires that 
you do some hacking that isn't very nice, and slightly buggy, 
but it usually works. The reason you would want to create the 
routine as part of your code is because it's much faster to 
compile a definition procedure as part of your code as opposed 
to compiling the procedure into a resource, installing it, and 
then running the program that uses it. 

As my first article explained, there are several ways to 
create the Definition Routine as part of your program. The 
way I choose to include the Definition Routine is shown 
below: 


var (our menu handle) 
myMenuHd] : MenuHendle; 


(this is the proc that will become a resource) 
TheMenuProc(..... ); 


(first, we need to get a menu handle!) 
): 


myMenuHdl^*.menuProc := NewHandleC0); 

(third, we make the handle point to a pointer to our 
routine. This, in effect makes a handle to our routine 
(which is what we went through all this for!). We can do 
this because the routine is in the first code segment that 
is always locked.) 


myMenuHd1**.menuProc* := Ptr(@TheMenuProc); 


Mike Shulster's approach to creating a definition routine 
is a bit different, but works just as well. He makes a 6 byte 
resource, MDEF, WDEF, etc. All the resource contains is a 
JMP XXXXXXXX instruction. After he gets the handle to 
the routine, he patches the contents of the resource so that it 
will to jump back to his code!!! This method is shown 
below. 
var (our menu handle} 

myMenuHd] : MenuHandle; 

(this is the proc that will become a resource) 
TheMenuProc(..... ); 
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m (first, we need to get & menu handle. This will read 
the 6 byte "defintion" resource and place a hendle to it 
in the menu record) 


(get a ptr to the resource data) 
MyPtr := Pointer CmyMenuHd1*~.menuProc); 
(skip UMP instruction but not address) 
MyPtr := PointerCOrd4(myPtr) + 2); 
(end stuff the address of the menu proc in the 
XX portion of the resource} 
MyPtr* := Ord4C@TheMenuProc); 
(the resource data now consists of a jump back to 
the applications code that implements the 


tion routine.) 


These methods should only 
development! 

Normally, a fairly large program consists of more than 
one code segment, therefore you can never be sure if the 
procedure is going to be part of segment one (which is 
locked). You could Hlock the code segment the code is a part 
of, but this would result in heap fragmentation which is a BIG 
NO NO! 

How do you compile the Definition Procedure into a 
resource? TML Pascal allows you to do this very easily. 
When I wrote this, mid-August, the only other compiler that I 
know of that had this capability was Lisa Pascal. 

A TML Pascal shell is shown below for a program that 
is to be compiled into a resource. Note: it must be compiled 
with the create desk accessory option checked. 


XXXXXX 
def ini 


be used during 


program TheDefProcProgrem; 
($C type id [attribute] [name }} 
($H ee 


( 
procedure TheDefProc(..... ); 
const 


(------------------------- RESOURCE ENDS HERE --) 


begin (no main program allowed) 
end. 

The type, is the resource type, id is the resource id, the 
name and attribute fields are optional and are used to set the 
resources name and attributes. Always remember to compile 
your tested Definition Routines into a resource when they are 
finished! The $H " tells the compiler that the desk accessory 
header should not be linked to the Definition Routine. [The 
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$C directive tells the compiler to create a code resource out of 
the first procedure. -Ed] 

There are a number of GREAT things that can be done 
with definition routines. By the way, have any of you seen 
dBase Mac? The PopUps used in dBase Mac are custom 
Control Definitions, which we cover next month! 

Introduction to Wdef Routines 

This month we are covering Window Definition 
Routines. What is a window definition routine? It is a 
procedure that defines a particular type of window. The 
routine controls the way windows are drawn, the regions of the 
window, the highlighting, how they are grown, etc. In 
general, Window Definition routines define windows’ 
appearance and behavior. The standard type of Macintosh 
window has been pre-defined for you and is stored in the 
system file. You may however want to define your own type 
of window. The windows in Microsoft's Flight Simulator are 
good examples of non-standard windows. 

The window definition procedure I decided to use 
for an example doesn't create a non-standard window but it 
shows exactly how the standard menu definition works! The 
standard definition routine was written in 68000 Assembler, 
by Andy Hertzfeld (my hero), but ours will be written entirely 
in TML Pascal. There isn't any noticeable speed difference 
between the standard Menu Def and our imitation. 

The pascal definition and general outline for a 
Window Definition function follows: 


function MyWindowDef(varCode : Integer; 
theWindow : WindowPtr; 
message : Integer; 
param : LongInt) : LongInt; 

type 

RectPtr = “Rect; 


var 
aRectPtr : RectPtr; 
procedure DoDrewCeWindow : WindowPtr; parem : LongInt2); 
begin 
... (drew window - check param to draw go-away or frame} 
end 
function DoHitCaWindow 
LongInt; 
begin 
. (check to see if the point is in window, return region) 


WindowPtr; param LongInt) 


end; 
procedure DoCalcRgnCeWindow : WindowPtr); 
begin 
... ( calculate the windows structure and content rgns) 
end; 
procedure DoInitCaWindow : WindowPtr); 
begin 
... ( allocate any additional storage needed for window) 


end; 
procedure DoDisposeCeWindow : WindowPtr); 


begin 
... ( dispose of what you created in DoInit) 
end; 
procedure DoGrowCaWindow : WindowPtr; aRect : Rect); 
begin 


... (drew the grow- outline of the window in the rect) 


end; 
procedure DoGIconCeWindow : WindowPtr); 
begin 
... (draw the grow icon) 
end; 
begin 
cese message of 
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wDrewMsg 
DoDraw(theWindow, peram); 
wHitMsg : 
MyWindowDef := DoHitCtheWindow, param); 
wCalcRgnMsg : 
DoCalcRgn(CtheWindow); 
wInitMsg : 
DoInitCtheWindow); 
wDisposeMsg : 
DoDisposeCtheWindow); 
wGrowMsg : 
begin 
eRectPtr := RectPtr(param); 
DoGrowCtheWindow, aRectPtr~); 
end; 
wGIconMsg : 
DoGIcon( theW indow); 
end; 
end; 


The Parameters 

The varCode parameter tells the window definition 
routine what variation of the window we are doing. For 
example, in the standard round-corner document window, the 
varCode parameter tells the definition function the radius of 
the comers. 

The window manager gets the varCode in the following 
ways: When you create a window from a resource, you 
specify the definition ID in the Window Record. The 
definition ID is actually the resource ID of the window 


definition function in the upper 12 bits, and the varCode in the 
lower 4 bits: 
The Window manager calls the Resource manager with 


defHaendle := GetResource('WDEF',resourceID); 
and stores the result in the windowDefProc field of the window 
record in the following format. 


The variation code is then passed to the Window Definition 
function. 

TheWindow is a Pointer to the window the message 
effects. Remember that type-casting the window pointer, 
which is a GrafPtr, into a Window Peek, is done by the 
following: 
aWindowPeekVar := WindowPeekCaWindowPtrVar ); 

The message parameter tells you what operation you are 
to perform. The possible messages are: wDraw, wHit, 
wCalcRgns, wNew, wDispose, wGrow, and wDrawGlcon. 

The param parameter is used to pass all kinds of stuff to 
your definition funtion. For instance, in the draw routine, you 
check the value of it to see if you are to draw the entire frame 
or just "toggle" the highlight state of the window's go-away 
box. In the grow message, it is a pointer to a rect and in the 
hit message it is the point in which the mouse button was 
pressed. 

DoDraw Procedure 

The DoDraw procedure is called in response to a wDraw 
message. It examines the value of param, if it is equal to 
wInGoAway then it toggles the state of the go-away box. In 
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our example we do the highlighting differently, we just call 
InvertRect to toggle the state. If the value of param is 0, then 
we draw the entire window frame. The current port will 


15 43 0 


resourcelD code 


already be set to the WindowMgrPort. If the go-away flag is 
true in the window record, we also draw the go-away region. 
If the highlighted field is true, we "highlight" the title bar, 
this shows the user that this window is the currently active 
one. 


27 23 0 
| |eode defHandle 
DoHit Function 


The DoHit procedure is called in response to a wHit 
message. It is past the point (global coords) in the param 
parameter. It should determine where the point "hit" and 
return one of the following: 1) It should return wNoHit if it 
wasn't in the window. 2) It should return wInContent if the 
point was in the content region, and 3) it should return 
wInGrow if it was in the grow Region. It should also return 
wInGoAway if it was in the go-away rgn. The constants 
wInGrow and wInGoAway should only be returned if the 
window is active (highlighted = true). 

DoCalcRgns Procedure 

The DoCalcRgns procedure calculates the window's 
content and structure regions. The structure region is the 
entire window, including the title bar (if any), any shading, 
and the frame lines. In short it is the entire window. The 
content region is the area in which all drawing to the window 
will be clipped. It is always a sub-set of the structure region. 
Both of the regions are calculated from the windows portRect. 
The results of these calulations are stored in the windows 
StrucRgn and contRgn fields. 

The Dolnit Procedure 

The Dolnit procedure is not used in our example. Its 
reason for being there, however, is to allow a definition 
procedure to create any additional data structures it may need. 
A handle to these data structures is stored in the dataHandle 
field of the window record. I used this feature when creating 
one of the TML Examples. The example creates a non- 
standard window, with highlighting like that on the Lisa 
(whoops.. Mac-XL). Its main feature is that it has a menu bar 
underneath the window's title bar, allowing each window to 
have its own menus. Anyway, in that example, I needed to 
store a bunch of menu handles when the window is created, 
and this message allowed me to do that. 

DoDispose Procedure 

The DoDispose procedure simply "un-o's" anything the 
DoInit procedure does. For instance, in the example I 
explained above, it calls DisposMenu for all the menus I 
created in the DoInit procedure. The DoDispose procedure, as 
you may have guessed, is called as a result of a CloseWindow 
or DisposeWindow call. 

DoGrow Procedure 
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The DoGrow procedure is called after the Window 
definition function has returned a inGrow result from the Hit 
test routine. The window manager then sets the grafPort to 
the window manager port, the pen mode to notPatXor, and the 
penPat to gray. Then, as long as the user has the mouse 
down, the window manager repeatedly calls the definition 
function with the wGrow message. The DoGrow procedure 
must then draw the grow-image of the window, scaled to the 
rect which is passed by pointer in the param parameter. Our 
routine draws the outline of the entire window. It also shows 
the lines which delimit the title bar and the scroll bar areas. 

DrawGlcon Procedure 


WindowFrame 


Reti eet ettet Co nte nt Rg n 
Structure Rgn = contentRgn + windowFrame 


The DrawGlIcon procedure checks to see if the window is 
active. If active, it draws the grow icon in a manner 
that shows the window can be grown. If it is inactive, the 
DrawGlcon procedure draws the grow icon area in a manner 
which shows the window temporarily cannot be sized. 


RegWDEF .Pas 


This program illustrates the use of a standard Window 

Definition routine. It behaves exactly like the 
tandard 

window definition procedure. -=< almost >=- 

This example was written by Darryl Lovato. 

Copyright (c) 1986 by TML Systems 


^ 1$ 3$ 31$ 1$ (O0 ts 1$ 13$ 13$ — 


program RegWDEF; ( the beginning) 
($1 MemTypes.ipas ) 
($1 QuickDrew. ipas ) 
($1 OSIntf. ipas 

($1 Toolintf. ipas ) 


($T APPL RWDF 
($8* 

($L RegWDEFRes 
( 


) Global Contants Follow 
const 
AppleMenuID = 1; ( the Apple menu) 


( read the memory defs) 

( read the quickdraw defs) 

( read operating system defs) 
{ read the toolbox equates) 


( set the type and creator) 


) 
) ( set the bundle bit) 
)( link the resource f ile too...) 
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AboutRegWDEFID = 1; ( the About item) 


FileMenuID = 2; the File menu) 
QuitID = 1; 
EditMenuID = 3; the Edit menu) 


( 
( 
the Quit item) 
( 


WindResID » 1; 
AboutID = 3000; 


the resource id of my window) 
( About Dielog id) 


Global Veriables Follow 


"— Bon 


ver 
myMenus : ArraylAppleMenuID..EditMenuID] of MenuHendle; 
Done : Boolean; ( true when user selects quit) 
RegWDEFWindow : WindowPtr; (the window) 
GrowArea : rect; ( rect wind can be grown) 
Dragárea : rect; ( rect wind cen be dregged) 
myWindowPeek : WindowPeek;( to get at the windows fields) 


MyWindowDef function 


program RegWDEF; { the beginning) 

( read the memory defs) 

( read the quickdraw defs) 
( read operating system defs) 
( read the toolbox equates) 


($1 MenTypes.ipes ) 
($1 QuickDrew. ipes ) 
($1 OSIntf. ipes 

($I Toolintf.ipas 


($T APPL RWDF 
B+ 

($L RegWDEFRes 

( 


) Global Contents Follow 
const 
AppleMenuID = 1; ( the rie menu) 
( 


( set the bundle bit) 


) 
) 
} ( set the type and creator) 
)( link the resource file too...) 


AboutRegWDEFID = 1; ( the About item) 
FileMenuID s 2; the File menu) 
QuitID = 1; ( the Quit item) 


EditMenuID = 3; ( the Edit menu) 
WindResID = 1; ( the resource id of my window) 
AboutID = 3900; ( About Dialog id) 

( 

N Global Variables Follow 

ver 


myMenus : Arrey[AppleMenuID. .EditMenuID] of MenuHandle; 
Done : Boolean; ( true when user selects quit) 
RegWDEFWindow : WindowPtr; (the window) 

GrowArea : rect; ( rect wind can be grown) 
Dragdrea : rect; ( rect wind cen be dragged) 
myWindowPeek : WindowPeek;{ to get at the windows fields) 


MyWindowDef function 


—» V 3$ Bee 


unction MyWindowDef(varCode : Integer; 


program RegWDEF; ( the beginning) 


program RegWDEF; ( the beginning) 


program RegWDEF; { the beginning) 


program RegWDEF; — ( the beginning) 
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( read the memory defs) 
( read the quickdrew defs) 
( read operating system defs) 


($I MemTypes.ipes ) 
($1 QuickDraw. ipas ) 
($1 OSIntf. ipas 


($I Toolintf. ipas ) ( read the toolbox equates) 
($T APPL RWDF ) ( set the type and creator) 
($8* ) ( set the bundle bit) 

($L RegWDEFRes )( link the resource file too...) 
( 

8 Global Contants Follow 

const 


AppleMenuID = 1; ( the Apple menu) 
AboutRegWDEFID = 1; ( the About item) 
FileMenuID = 2; ( the File menu) 


QuitID = 1; ( the Quit item) 
EditMenuID = 3; ( the Edit menu) 
WindResID = 1; ( the resource id of my window) 
AboutID = 3000; ( About Dialog id) 
( 
) Global Variables Follow 
ver 


myMenus : Array[AppleMenuID..EditMenuID] of MenuHendle; 
Done : Booleen; true when user selects quit) 
RegWDEFWindow : WindowPtr; (the window) 

GrowArea : rect; ( rect wind cen be grown) 
DregÁrea : rect; ( rect wind can be dragged) 
nyWindowPeek : WindowPeek; ( to get at the windows fields) 


( 
tt 
N MyWindowDef function 
function MyWindowDef(varCode : Integer; 
theWindow : WindowPtr; 
message : Integer; 
param : LongInt) 
: LongInt; 
ATE Semi-global types within the WDEF ------------- 
type 
RectPtr = “Rect; 
ae Semi-global vars within the WOEF ------------ ) 


ver 
eRectPtr : RectPtr; 
nyWindowPeek : WindowPeek; 


So DoDrawMessage procedure --------------- ) 
procedure DoDrewMessage(WindToDrew : WindowPtr; 
DrawParam : LongInt2; 


var 
TitleBarRect : Rect; 
CurrentY : Integer; 
index : Integer; 
GoAwayBox : Rect; 


procedure DrewWindowTitleCeWindowPeek : WindowPeek; 
theBox : Rect); 


ver 
TitleWidth : Integer; 
TitleBarWidth : Integer; 
leftEdge : Integer; 
ereseR : Rect; 


begin 
TitleWidth := StringWidthCeWindowPeek^ . tit leHaendle^^); 
TitleBarWidth := theBox.right - theBox. left; 
leftEdge := (TitleBarWidth - TitleWidth) DIV 2; 
if aWindowPeek* .GoAwayFlag then 
if leftEdge « 32 then 
leftEdge := 32; 
leftEdge := leftEdge + theBox.left; {local to global!!!) 
ereseR := theBox; 
InsetRectCeraseR, 1, 1); 
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eraseR. left := leftEdge - 6; 

eraseR right := leftEdge + TitleWidth + 6; 
EraseRect(ereseR); 
MoveToClef tEdge, theBox.bottom - 5); 
DrewStringCeWindowPeek*^ . t itleHandle^*); 
end; 


begin 

myWindowPeek := WindowPeek(WindToDrew); 

if myWindowPeek* visible then(if the wind is visible, draw 
it 


begin 
T itleBerRect := myWindowPeek^ .strucRgn^^ .rgnBBox; 
if DrewPerem <> 8 then (we just need to toggle goAway 
box 
begin {make room for title bar) 
TitleBerRect.bottom := TitleBerRect.top + 19; 
GoAwayBox := TitleBarRect; 
GoAwayBox. top := GoAwayBox.top + 4; 
GoAwayBox. left := GoAwayBox. left + 8; 
GoAwayBox.bottom := GoAwayBox.bottom - 4; 
GoAwayBox.right := GoAwayBox. left + 13; 
InsetRect(GoAwayBox,2,1); ( move in on the sides) 
InvertRectCGoAwayBox2; 
end (of if DrawParam = inGoAway) 
else (we need to drew window frame, and possibly hilite 
it 
begin 
PenNormal ; 


FrameRect(TitleBarRect); 
(make room for title bar} 
TitleBarRect bottom := TitleBarRect.top + 19; 


FrameRect(TitleBarRect); 
InsetRect(TitleBarRect, 1,1); (shrink by 1) 
EraseRect(TitleBarRect); 
InsetRect(TitleBarRect,-1,-1); (expand by 1) 


if myWindowPeek^.hilited then ( add hiliting ) 
begin 
currentY := TitleBarRect.top + 4; (draw the 
pattern) 
for index := 1 to 6 do 

begin 
MoveTo(TitleBarRect.left + 2, currentY); 
LineToCTitleBarRect.right - 3, currentY); 
currentY := currentY + 2; 


end; 

(drew title) 

DrewWindowTitleCnyWindowPeek, TitleBarRect); 

if nyWindowPeek^.GoAwayFlag then (goaway ) 
begin 
GoAwayBox := TitleBarRect; 
GoAwayBox. top := GoAwayBox.top + 4; 
GoAwayBox. left := GoAwayBox.left + 8; 
GoAwayBox bottom := GoAwayBox.bottom - 4; 
GoAwayBox.right := GoAwayBox. left + 13; 
EraseRect (GoAwayBox); 
InsetRect(GoAwayBox, 1,8); ( move in on sides) 
FrameRect(GoAwayBox); (and draw the box) 

end; 

end 
else (just drew the title) 
DrewWindowTitleCmyWindowPeek,TitleBarRect?; 
end; (of if DrawParam = inGoAway then.. else...) 
end; (of if window is visible...) 
end; 


Poe S DoHitMessage function --------------- ) 


function DoHitMessage(WindToTest : WindowPtr; 
theParam : LongInt) : LongInt; 


var 
globalPt : Point; 
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eRect : Rect; 
GoAwayBox : Rect; 
aWindowPeek : WindowPeek; 
tempRect : Rect; 
begin 
globalPt.h := LoWordCtheParem); 
globalPt.v := HiWord(theParam); 
eWindowPeek := WindowPeek(WindToTest); 
eRect := eWindowPeek^ .strucRgn^^ .rgnBBox; 
eRect.bottom :- aRect.top * 19; (create tBar Rect) 
tempRect := eWindowPeek^ .strucRgn^^ .rgnBBox; 
if PtInRect(globalPt, tempRect) then (in structure rgn?) 
begin 
tempRect := aWindowPeek^.contRgn^^ .rgnBBox; 
if PtInRect(globalPt, tempRect) then (if in content rgn) 
begin 
if aWindowPeek* .hilited then (check the content box) 
begin 
eRect := eWindowPeek^ .contRgn^^ .rgnBBox; 
eRect.top := eRect.bottom - 15; (rect in low right) 
eRect.left := eRect.right - 15; 
if PtInRectCglobalPt,aRect) then (it was in drag 
box 
DoHitMessage := wInGrow 
else 
DoHitMessage := wInContent; 
end 
else 
DoHitMessage := wInContent; 
end 
else if PtInRect(globalPt,aRect) then (in drag or go- 


begin 
if eWindowPeek^.hilited then (check go-away box) 
begin 
GoAwayBox := aRect; 
GoAwayBox.top := GoAwayBox.top + 4; 
GoAwayBox. left := GoAwayBox. left + 8; 
GoAwayBox.bottom := GoAwayBox.bottom - 4; 
GoAwayBox.right := GoAwayBox.left + 13; 
InsetRect(GoAwayBox, 1,8); ( move in on the sides} 
if PtInRect(globalPt,GoAwayBox) then (in drag box) 
DoHitMessage := wInGoAway 
else 
DoHitMessage :- wInDrag; 
end 
else 
DoHitMessage := wInDrag; 
end 
else (it was in our window frame) 
DoHitMessage := wNoHit; 


away 


end 


else (it wasn't in our window at a11} 
DoHitMessage := wNoHit; 


end; 

(--------~=-- DoCalcRgnsMessage procedure ------------- 
procedure DoCalcRgnsMessage(WindToCalc : WindowPtr); 
ver 


tempRect : Rect; 
aWindowPeek : WindowPeek; 
eRgn : RgnHandle; 


tempRect := WindToCalc*.PortRect; 


OffsetRectCtempRect, -WindToCalc^.PortBits.Bounds.Left, 
-WindToCalc* .PortBits.Bounds.Top?); 


aWindowPeek := WindowPeek(WindToCalc); 
RectRgnCaWindowPeek*^ . contRgn, tempRect); (content rgn) 


InsetRect(tempRect,-1,-1); 


tempRect.top := tempRect.top - 18; {make room for title bar} 
RectRgnCaWindowPeek^ .strucRgn, tempRect); (struct rgn) 
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(eE DoGrowMessage procedure ------------- ) 
procedure DoGrowMessage(WindToGrow : WindowPtr; 
theGrowRect : Rect); 


a (note: we really dont need the window ptr, just the 
rect 
theGrowRect.top := theGrowRect.top - 19; 
FrameRect( theGrowRect); 
theGrowRect.top := theGrowRect.top + 18; 
MoveTo( theGrowRect. left, theGrowRect.top); (drag area) 
LineToCtheGrowRect .right, theGrowRect . top); 
MoveToCtheGrowRect.right -15, theGrowRect. top); 
LineToCtheGrowRect.right - 15, theGrowRect bottom); 
MoveTo(theGrowRect. left, theGrowRect.bottom - 15); 
LineToCtheGrowRect .right, theGrowRect.bottom - 15); 
end; 


(7--—---7-7-7'-*- DoDrawSizeMessage procedure ------------ ) 
procedure DoDrewSizeMessage(WindToDrew : WindowPtr); 
var 

tempRect : Rect; 

boxRect : Rect; 
begin 

SetPortCWindToDraw); 

tempRect := WindToDrew^ .PortRect; 

tempRect. left := tempRect.right - 15; 

tempRect.top := tempRect.bottom - 15; 

boxRect := tempRect; (the grow icon area) 


myWindowPeek := WindowPeek(WindToDraw); 


tempRect.top := WindToDrew^.PortRect.top; (scroll frame) 
EraseRect(tempRect); 
MoveToCtempRect. left, tempRect. top); 
LineToCtempRect. left, tempRect .bottom); 
tempRect.right := tempRect.right - 15; 
tempRect.top := tempRect.bottom - 15; 
tempRect. left := WindToDraw* .PortRect. left; 
EraseRect( tempRect); 

tempRect.right := tempRect.right + 15; 
MoveToCtempRect . lef t, tempRect.top); 
LineToCtempRect .right, tempRect. top); 


if myWindowPeek^.hilited then (draw the grow icon) 
begin 
InsetRect(boxRect, 1, 1); 
boxRect.top := boxRect.top + 4; 
boxRect.left := boxRect.left + 4; 
FremeRectCboxRect); 
boxRect.right := boxRect.right - 2; 
boxRect.bottom := boxRect.bottom - 2; 
Of fsetRect(boxRect,-2,-2); 
EraseRect(boxRect); 
FrameRect(boxRect); 
end 
else {erase the grow icon) 
begin 
InsetRectCboxRect, 1, 1); 
EraseRect(boxRect); 
end; 


begin (case out on message & jump to appropriate routine} 
MyWindowDef := Ø; (but first init result 
case message of 


wDrew : ( draw window frame} 
begin 
DoDrewMessageCtheWindow, param); 
end; 
wHit : ( tell what rgn the mouse was pressed in) 
begin 
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MyWindowDef := DoHitMessageCtheWindow,parem); 


end; 
wCalcRgns : { calculate structRgn and contRgn) 
begin 
DoCalcRgnsMessage( theWindow); 
end; 
wNew : ( do any additional initialization} 
begin { we dont need to do any) 
end; 
wDispose : ( do any additional disposal actions) 
begin ( we dont need to do any) 
end; 
wGrow : ( drew window's grow image) 
begin 


eRectPtr := RectPtr(param); 
DoGrowMessage( theW indow, eRectPtr^); 


end; 
wDrewGIcon :  ( draw size box in content rgn) 


begin 
DoDrawS izeMessage( theWindow); 
end; 
end; 

end; 
(s 
ij ShowAbout procedure 
8 
procedure ShowAbout; ( give me some credit) 
ver 


theDlog : DialogPtr; 
theItem : Integer; 
begin 
theDlog := GetNewDialogCAboutID,nil,Pointer(-1)); 
ModalDialog(nil, theI tem); 
DisposDialog( theD1og); 
end; 


procedure ProcessMenu(codeWord:Longint); 
ver 
menuNum : Integer; 
itemNum : Integer; 
NemeHolder : str255; 
dummy : Integer; 
yuck : boolean; 
begin 
if codeWord € Ø then ( nothing was selected) 
begin 
menuNum :- HiWordCcodeWord); 
itemNum := LoWord(codeWord); 
case menuNum of ( the different menus) 
AppleMenuID : 
begin 
if itemNum < 3 then 
begin 
ShowAbout ; 
end 
else 


begin 
GetI temCmyMenus [AppleMenuID], 
itemNum, NameHolder ); 
dummy := OpenDeskAcc(NameHolder ); 
end; 
end; 
FileMenuID : 
begin 
Done := true; 
end; 
EditMenuID : 
begin 
yuck := SystemEditCitemNum - 12; 
end; 


end; 
HiliteMenuC0); 
end; 
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end; 


procedure DealWithMouseDowns( theEvent: EventRecord); 
ver 

location : Integer; 

windowPointedTo : WindowPtr; 

mouseloc : point; 

windowLoc : integer; 

VendH : Longint; 

Height : Integer; 

Width : Integer; 


begin 
mouseLoc := theEvent.where; 
windowLoc := FindWindowC(mouseLoc, windowPointedTo); 
case windowLoc of 
inMenuBar : 
begin 
ProcessMenu(Menuse lect (mouseLoc )); 
end; 
inSysWindow : 
begin 
SystemC] ickCtheEvent , windowPointedTo); 
end; 
 inContent : 
begin 
if windowPointedTo € FrontWindow then 
begin 
SelectWindow(windowPointedTo); 
end; 
end; 
inGrow : 
begin 
if windowPointedTo € FrontWindow then 
begin 
SelectWindow(windowPointedTo); 


begin 
GrowArea. left := 150; 
GrowArea.top := 50; 
VandH := GrowWindow(windowPointedTo, 
mouseLoc, GrowArea); 

if VandH © Ø then 

begin 

Height := HiWord(VandH); 
Width := LoWord(VandH); 
if Height: 50 then 


Height := 50; 
if Width « 158 then 
Width := 159; 


SizeWindow(windowPointedTo, Width, Height, true); 
InvelRect(windowPo intedTo*^ .portRect?; 
end; 
end; 
end; 
inDrag : 
begin 
DragWindow(windowPointedTo, mouseLoc, DragArea); 
SelectWindowCwindowPointedTo); 
end; 
inGoAway : 
begin 
if TrackGoAwayCwindowPointedTo,mouseLoc) then 
Done := true; 
end; 
end; 
end; 


procedure DealWithKeyDowns( theEvent: EventRecord); 
type 
Trick = packed record 
case boolean of 
true : Clong : Longint); 
false : (chr3,chr2,chri,chr@ : char) 
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end; 
var 
CharCode : char; 
TrickVar : Trick; 
begin 


TrickVar.long := theEvent.message; 
CharCode := TrickVar.chr@; 
if BitAndCtheEvent.modif iers,CmdKey) = CmdKey then 
begin 
ProcessMenuCMenuKeyCCharCode 22; 
end; 
end; 


procedure DealWithActivates( theEvent: EventRecord); 
var 
TargetWindow : WindowPtr; 


begin 
TargetWindow := WindowPtr(theEvent.message); 
DrewGrowIcon(TargetWindow); 
if OddCtheEvent.modif iers) then 
begin 
SetPortCTergetWindow); 
end; 
end; 


procedure DealWithUpdatesCtheEvent: EventRecord); 
var 

UpDateWindow : WindowPtr; 

tempPort : WindowPtr; 


begin 
UpDateWindow := WindowPtrCtheEvent . message); 
GetPortCtempPort); 


SetPortCUpDateWindow); 
BeginUpDateCUpDateWindow); 
EraseRect(UpDateWindow^.portRect); 
FillRectCRegWDEFW indow^ .PortRect,1tGray); 
DrawGrowIconCUpDateW indow); 
EndUpDateCUpDateWindow); 
SetPortCtempPort); 
end; 


(# MainEventLoop procedure 
tt 
") 
procedure MainEventLoop; 
ver 
Event : EventRecord; 
ProcessIt : boolean; 
begin 
repeat 
SystemTask ; 
ProcessIt := GetNextEventCeveryEvent, Event); 
if ProcessIt then 
begin 
case Event.what of 
mouseDown : DealWithMouseDowns(Event); 
AutoKey : DealWithKeyDowns(Event); 
KeyDown : DealWithKeyDowns(Event); 
ActivateEvt : DealWithActivates(Event); 
UpdateEvt : DealWithUpdates(Event); 
end; 
end; 
until Done; 
end; 


procedure SetupMemory; 


x := ORD4CApplicZone) + 128000; 
SetApplLimitCPointer (x2); 
MaxApplZone; 

MoreMesters; 
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MoreMasters; 
MoreMasters; 
end; 


procedure SetupLimits; 
var 
Screen : 
begin 
Screen := ScreenBits.bounds; 
with Screen do 
begin 
SetRect(Dragdrea, lef t*4, top+24,right-4, bottom-4); 
SetRectCGrowArea, left, top+24, right, bottom); 
end; 
end; 


( set up the dragging growing rects) 
Rect; 


procedure MakeMenus; ( get the menus ) 


index : Integer; 
begin 
for index := AppleMenuID to EditMenuID do 
begin 


nyMenuslindex] := GetMenuCindex); 
Inser tMenuCmyMenus[ index 1,0); 


en 
AddResMenuCmyMenus [App leMenuID1, 'DRVR' ); 
DrawMenuBar ; 


(cthansaesuesunsnesnnemnennonennnnneeeeneententne 


Program Execution Starts Here 
n P E e Mar a E ea 


begin 


end 


Done := false; ( we just started!!!) 
FlushEventsCeveryEvent, 0); (get rid of lingering events) 


InitGref CéthePort); ( we need QuickDrew) 

InitFonts; ( we need Fonts) 

InitWindows; ( we need Windows) 

InitMenus; ( we need Menus) 

TEInit; ( we need Text Edit) 

InitDialogs(nil); ( we need Dialogs) 

InitCursor ; ( show the cursor) 

SetupLimits; { initialize the screen sizes) 

SetupMemory; do some memory management) 

MakeMenus; { go create the menus 

RegWDEFWindow := GetNewWindow(WindResID, 
nil,Pointer(-1)); 

myWindowPeek := WindowPeekCRegWDEFW indow); 

(note, the window is created invisible} 

myWindowPeek* .windowDefProc := NewHandle(@); 

myW indowPeek* .windowDefProc* := PtrC@MyWindowDef ); 


ShowW indowCRegWDEFWindow); (... 
SetPortCRegWDEFW indow); 
FillRectCRegWDEFW indow^ .PortRect, 1tGray); 


.now we can show it!) 


.and take care of business) 


MainEventLoop; T 


(rate eN 
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Advanced Macing 


Reduce Your Time in the Traps! 


Life in the fast lane 

The Macintosh ROM 
subroutines are called with “trap” 
instructions, intercepted by 
dispatching software which 
interprets the trap and calls the 
routine. This method is very 
general, providing compatibility 
with future ROMs and allowing 
buggy routines to be replaced. 

Its also slow, taking about 45 
microseconds for the dispatch 
process. This article tells you a way 
to avoid the dispatcher without 
losing its generality. Since the 
timing differences are measured in 
microseconds, there's also a 
discussion of techniques for measuring the time consumed by 
a piece of code. Also, a program is included to show the 
alternate way to call the ROM and how to measure the times 
used by different methods. 

Avoiding traps 

When a program executes a trap instruction, the 68000 
detects the “error” and transfers control to the trap dispatcher 
pointed to by the longword at $0028. The dispatching 
software must, among other things: 


* preserve some registers on the stack 

e fetch the trap instruction from the code 

e decide if the trap is a Toolbox or OS call 

* lookup the trap number to find whether the routine is in 
RAM or ROM, and what its address is 

e handle the “auto-pop” and "pass AO” bits 

e call the routine 

e restore registers from the stack 


Most of this work can be avoided if you know the 
routine's address and call it directly, but this is a bad idea for 
two reasons. First, the address may change in future ROMs. 
Second, Apple distributes “patches” to ROM routines by 
changing the dispatch table to call new versions in RAM — if 
your program "knows" the address, it'll call the old, buggy 
ROM routines, ignoring the new RAM-based ones. 

There is a balance between hardwiring the address and 
using the trap dispatcher for every call. The Toolbox 
"GetTrapAddress" function decodes a trap instruction for you 
and returns the address of the routine, just as the dispatcher 
does. You can do this decoding just once in your program, 
save the address, and repeatedly call it later. 

The main reason not to bypass the dispatcher is that it 
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Mike Morton 
Senior Software Engineer 


Lotus Development Corp. 
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Cambridge, MA 


Pascal 


traptime 


If launching from a floppy, wait for it to stop and click to begin. 
number of loops:10000; base time is: ? 

time for usual method' is 38 

time for calling my oun routine is: 30 

time for doing it in-line is 

time for doing it with de ldrobaddr: 18 


number of loops:100000; base time is: 77 

time for usual method is : 368 

time for calling my oun routine is: 285 he 
time for doing it in-line is : 47 

time for doing it with gettrapaddr: 174 


click to exit or take snapshot... 


Fig. 1 Our TrapTime Utility shows the difference! 


Saves a few registers across each call. If you're working in 
assembler, this is no problem — just save registers yourself, 
as needed. In most high-level languages, it also won't be a 
problem, since the registers lost are typically scratch registers: 
D1, D2, and A2. 
A high-level example 

First, let's look at the normal way of calling a Toolbox 
routine: the simple "SetPt" procedure, which sets the 
coordinates of a Quickdraw "point". The following example 
and the timing program are in TML Pascal; they should be 
easy to convert to other languages. 

Most programs include the Quickdraw unit, which 
declares "setPt" with 


procedure SetPtCVAR pt: point; h, v: integer); INLINE $4880; 


When you call the routine with the statement 


setPt (nyPt, x, y); {set the point ) 

it pushes the parameters on the stack and executes the 
instruction $A880 to trap to the dispatcher, which calls the 
routine. If you want to skip the cost of repeatedly decoding 
the trap, you can do it once like this: 


var setPtAddr:longint; ( addr of setPt ) 


setPtAddr := getTrapAddress ($4880); 


To call this address, declare a new routine like SetPt, but 
which produces different in-line 68000 code: 


procedure mySetPt 
(VAR pt: point; h, v: 
addr: longint); 


integer; 
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INLINE $205F, $4E90; 


Note the extra parameter to this routine: the address of the 
routine to be called. The instructions given in hex after the 
"INLINE" do a JSR to that address. The result is nearly the 
same as executing a trap, but faster. 

Calling with this interface is almost like a normal call; 
pass the address as a parameter: 


mySetPt CmyPt, x, y, setPtAddr); 


This can be used for most Toolbox calls - just declare 
your own routine (choose any name) with the same parameters 
plus the address parameter, and include the exact same 
"INLINE" code after it. Don't forget to initialize the address 
with GetTrapAddress before calling, or awful things will 
happen. 

Other high-level languages 

You should be able to use this method with almost any 
language which allows you to insert assembler code in your 
high-level program. Some languages may have trouble 
calling the ROM directly — for instance, many C compilers 
pass parameters differently than ROM routines do. Some C 
compilers allow you to choose the method of parameter 
passing; this will allow you to dispense with assembler 
altogether and just call the routine through a pointer (ask your 
nearest C guru how to do this). 

More straightforward approaches 

This approach assumes that “‘SetPt” is too slow. If you 
actually need Toolbox operations to be faster, consider writing 
the code yourself. You can write a procedure or function to 
assign two integers to the coordinates of a point — or just do 
the assignment yourself. For a simple operation, this 
approach is preferable to spending lots of effort avoiding the 
trap dispatcher. (The “K.I.S.S.” rule applies here: “Keep It 
Simple, Stupid.”) 

Speed improvements: hard data 

Let's get quantitative. Consider four ways to assign to a 

point: 


* the usual trap 

e calling the ROM directly with INLINE 
* calling your own procedure 

* doing the assignment in-line 


I wrote all four in Lisa Pascal and found these times on a 
Mac, and on a Lisa running MacWorks: 


Table: Time to assign to a point 
(all times in microseconds) 


Mac Li acWor 


Normal “SetPt” trap 67.7 84.9 

Pre-decoded call 22.8 25.6 

Roll-your-own 34.5 35.2 

Assign in-line 4.8 4.8 
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Writing your own procedure is slower than using the trap 
routines address! The ROM is so fast, compared to compiled 
Pascal, that it's worth the slightly more complicated call. Part 
of the speed is because the ROM is tightly-coded; part is 
because the Mac's video refresh slows down code in RAM. 

The fastest method is to forget about writing a procedure 
and do the assignment normally. This is fourteen times faster 
than using traps to call the ROM! (There's something to be 
said for the do-it-yourself approach.) 

I tried running the program on a Mac Plus, since its 
ROM dispatch table has been expanded for faster trap calls. 
The time for a normal trap is 58.9 microseconds, instead of 
67.7 microseconds. All the other times are nearly the same. 

Speed improvements: summary 

First, all this isn't worthwhile for most traps. If you 
want to speed up disk I/O, resource operations, etc., the 
microseconds saved at trap time are dwarfed by the amount of 
time for a disk transfer or to search a large resource. This trick 
is appropriate only in some situations. 

Second, some routines are best done by hand in simple 
code in your program. ROM tools such as "SetPt" exist for 
your convenience, not because they're hard to code. If you find 
they're taking too much time, change them to a few lines of 
your own code. 

But suppose you're trying to draw lines at top speed with 
repeated "LineTo" calls? Or use one of the simple bit 
manipulators in a loop? You may find that you can't easily 
write it yourself, but you can save 45 microseconds by calling 
into the ROM using a previously determined address. My 
estimate is that if a trap takes between 200 and 800 
microseconds, you should consider skipping the dispatcher. 

The timing program 

The program "traptime" found the times given in the 
table. It has four procedures to time methods, and a 
"getbasetime" procedure to find the overhead of a loop with no 
calls. You can write a similar program using the same design 
in nearly any language. 

Note that the program prints its results in ticks (60ths of 
a second) and doesn't compute the time for a loop iteration; I 
did the conversions to microseconds-per-iteration by hand, 
rather than trying to get Pascal to do fractional arithmetic. 

Timing methods 

Unfortunately, doing accurate timings is fraught with 
problems. This program tries to avoid these. Some points on 
timings: 

* Repeat your measurements to help detect “random” factors. 
Small discrepancies should be averaged; large ones should 
be found and removed. 

* Be careful when comparing routines: the four timing routines 
(and the "overhead" routine) are identical except for one 
section. Keeping this parallel structure makes your 
program a controlled experiment, helping you time only the 
differences between procedures. 

* Vary the loop size; make sure that your time per iteration 
converges as your loop gets bigger. 

* When waiting for the program, don't move the mouse or 
fiddle with the keyboard. This causes interrupts and affects 
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the timings. 

* I suspect you shouldn't have the disk spinning, nor have a 
debugger active while timing. (In practice, I can't detect any 
timing differences due to either of these factors.) 


In short, timing is a scientific experiment and is easy to 

ruin by not controlling the environment carefully. 
Conclusion 

Bypassing the trap dispatcher can be a valuable technique 
in a limited number of situations, allowing you to cut about 
45 microseconds off the time to call the ROM. It has some 
drawbacks such as losing register contents, and may be hard to 
implement in some higher-level languages. In addition, many 
ROM calls take so long that the savings isn't significant. 

Whatever technique you're interesting in optimizing and 
timing, accurate measurement is a matter of a careful, 
controlled approach. 
( traptime -- A program to time various methods of doing a 
toolbox trap: 

The usual method, calling a user-written routine to do the 
work, doing the work in-line, and calling the ROM routine 
directly without going through the trap dispatcher. Times for 
all routines are written on the screen in ticks for a given 


number of calls, then the number of calls is varied for 
improved accuracy. 


A November 1985. Modified for TML Pascal, June 
1986. 


program traptime (output); ( "Coutput)" lets us do writelns ) 


($1 MemTypes.ipas ) 
($I QuickDraw. ipas ) 
($I OSIntf.ipas ) 

($1 ToolIntf.ipas ) 


( we use Quickdraw graphics ) 
( and 0S definitions ) 
( and Toolbox calls ) 


var ( program-wide variables ) 
basetime: longint; ( constent overhead for the loop ) 
loops: longint; ( number of iterations to time ) 
start: longint; ( starting tickcount for 

timing ) 
Event :EventRecord; 
DoIt: Boolean; 
Finished:Boolean; 


(simple event loop for cmd-3) 
(getnextevent boolean) 
(event loop terminator) 


( getbasetime -- Find the time for the loop when nothing is 
done inside it.This tells us the overhead which should be 
subtracted from other timings. ) 


function getbasetime: longint; 
ver count: longint; 
begin; 

start := tickcount; 

for count := 1 to loops do 


{ loop counter } 


( snapshot starting time ) 
( loop a bunch of times... ) 
3 ...doing nothing each time ) 
getbasetime := tickcount-stert; ( calculate elapsed time ) 
end; ( function "getbasetime" ) 


( usualtime -- Find the time used to call the ROM the usual 
way. This, end all timing routines, should look as much as 
possible like "getbasetime". ) 


function usualtime: longint; 


var 
count: longint; ( loop counter ) 
pt: point; ( point to essign to ) 
x, y: integer; ( coordinates to assign to the point ) 
begin; 


start := tickcount; ( snapshot starting time ) 
for count := 1 to loops do( this time, inside the loop... ) 
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setpt (pt, x, y); ( ...we do the ROM call ) 
usualtime := tickcount-start; ( calculate elapsed time ) 
end; ( function "usualtime" ) 


( setmypt -- This isn't a timing function like the others; 
it's a replacement for the ROM's "setpt" routine; to see how 
fast we can do it ourselves. ) 
procedure setmypt (VAR pt: point; x, y: integer); 
begin; 

pt.h := x; pt.v :» y; ( assign to the coordinates; easy! ) 
end; ( procedure "setmypt" ) 


( myowntime -- Time assignment using our own procedure. ) 


function myowntime: longint; 


var 
count: longint; ( loop counter ) 
pt: point; ( point to assign to ) 
x, y: integer; ( coordinates to assign to point ) 
begin; 


start := tickcount; 
for count := 1 to loops do 
the loop... } 
setmypt (pt, x, y); ( ...we call our own routine ) 
myowntime := tickcount-start; { calculate elapsed time } 
end; { function myowntime } 


( snapshot starting time ) 
( this time, inside 


( inlintime -- The most straightforward way: we do the 
assignment in the loop. ) 


function inlintime: longint; 


ver 
count: longint; { loop counter } 
pt: point; { point to assign to } 
x, y: integer; ( coordinates to assign to point ) 
begin; 


start := tickcount; ( snapshot starting time ) 
for count := 1 to loops do ( this time, inside the loop... } 


begin; pt.h := x; pt.v := y; end;  ( ...we do assignment 
here 
inlintime := tickcount-start; ( calculate elapsed time } 
end; ( function inlintime ) 


( setptx -- This is another replacement for "setpt". It takes 
en extra perameter, the previously determined address of 
"setpt", and calls that address, leaving the other parameters 
for "setpt". Unfortunately, TMLPascal doesn't mimic Lisa 
Pascal closely enough to allow us to generate more than one 
word of code in a single declaration. So we have two 
procedures -- these MUST always be used together! TML says 
their 2.0 

release of the compiler will be Lisa-compatible on this 
Score, so this unsightly workaround won't be needed any more.) 


procedure sSetptx1 (var pt: point; h, v: integer; addr: 
longint); 

INLINE $205F; ( MOVE.L CAT)+ AO 

; pop routine's address into AQ.. ) 

procedure setptx2; 

INLINE $4E90; ( JSR (A0) ; „and cal! that address ) 
( gettrtime -- The last and most complicated way of calling 
the routine. We use the trap address to call it directly. ) 


function gettrtime: longint; 
var 

eddr: longint; 

count: longint; 


( actual address of "setpt" ) 
( loop counter 


pt: point; ( point to assign to ) 

x, y: integer; ( coordinates to assign to point ) 
begin; 

addr :- gettrapaddress ($8880); ( find where routine 
lives 


start :- tickcount; ( snapshot starting time ) 
for count := 1 to loops do begin ( inside the loop... ) 
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setptx! (pt, x, y, addr); ( ...we call on ROM. ) writeln; 
setptx2; ( (kludge to sneak in 2nd instruction ) 
end; loops := loops * 18; ( loop sizes increase exponentially ) 


gettrtime := tickcount-start; 


end; 
( calculate elapsed time ) 


end; ( function gettrtime ) f lushevents(EveryEvent, Ø); 
writeln C'click to exit or take snapshot..'); 
begin; ( 32% main program 23% ) Repeat 
writeln C'If launching from a floppy, wait for it to stop systemtask; 


and click to begin...'); 
while not button do; while button do; 
( wait for a click ) 


DoIt:zGetNextEventCEveryEvent,Event); 
if DoIt then 
Case Event.what of 
KeyDown: begin end; 


loops := 10000; ( start with a small loop size... ) Mousedown: begin Finished:-true; end; 
while loops <= 1000000 do ^ ( and go through several sizes) End; 
begin; Until Finished; 
basetime := getbasetime; ( find constant overhead ) end. ( of main progrem "treptime" ) 


writeln C'number of loops:', loops, '; base time is:', 


basetime); 
writeln C'time for usual method is..........: ', usualtime - !PAS$Xfer 
baset ime); 
writeln C'time for calling my own routine is: ', myowntime - trapspeed 
basetime); PAS$L ibrary 
writeln C'time for doing it in-line is......: ', inlintime - se 
beset ime); P reps 
writeln C'tine for doing it with gettrapaddr: ', gettrtime - 
basetime); 
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Extending TextEdit to Handle Tabs 
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tabEditor 


Bradley W. Nedrud has a PhD from the University of Illinois 
in low-temperature solid-state physics. He worked for four 
years at Hughes Aircraft Company, designing and building 
microwave circuits for communication satelites and managing 
the C-band receiver section. In 1985 he decided to write a 
microwave circuit CAD program, because a). he was very 
impressed with the Macintosh, b). he was disillusioned with 
the CAD programs currently available, c). he wanted to spend 
more time with his family, and d). he didn't know any better. 


A Simple (?) Way to Implement Tabs in 
TextEdit Windows 


In this column, I present a simple TML Pascal editor of 
very little interest since it does not allow scrolling, resizing, 
saving, or printing. It does, however, allow me to 
demonstrate the implementation of tabs in a textEdit window, 
which in itself is an extremely useful feature. And in the 
process, I will show how to manipulate the low-level 
QuickDraw routines via the QDprocs field of a GrafPort and 
how to customize the intrinsic miniEditor, TEDoText, and the 
intrinsic lineStart recalculator. 

In scientific program development, it's often desirable to 
arrange data in neat tables. This allows the user to quickly 
find what he wants without that feeling of panic one gets 
when confronted with a windowful of jumbled numbers. After 
all, the Macintosh is based on the principle that neatness 
counts (grossly simplified). Of course, scientific programs are 
not the only ones that use a table format. Database managers, 
editors, even language output routines all need to produce 
tables, and tables means TABS! 

When I turned to IM, I read that famous line, "Although 
TextEdit is useful for many standard text editing operations, 
there are some additional features that it doesn't support. 
TextEdit does not support... tabs." At that time I was more 
naive then now and I felt something as intuitive and useful as 
tabs should be easy to implement. I started by writing a 
routine that measured the text from the first character on a line 
(following the CR of the previous line) up to a tab using 
TextWidth, subtracting that from the calculated pixel distance 
to the next larger tab and then dividing that by the width of a 
space. I then TEKeyed in that number of spaces. Simple as 
that was, the routine actually sort of worked, with two major 
drawbacks. First, the window didn't edit at all like it should. 
For example, TEClick would not treat the tab as an entity, so 
you could select positions between any of the spaces. Also, 
as soon as text was added or subtracted, the table reverted to a 
jumble. The second drawback was that the entries in columns 
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€ File Edit 


New E 


The quick brown fox jumped over the lazy dogs back. 
And then he jumped again. 
And again! 
Four times?? 
again. Y 


Fig. 1 This Text Edit Record tabs! 


And thenhe jumped 


Simple window with tabs in the text 


just wouldn't line up exactly. In proportional fonts, letters are 
all different widths, and adding spaces can only align text to 
the nearest half space-width. This gave ragged looking 
columns (much like in MicroSoft Basic's output windows) and 
just didn't project the kind of polished image I wanted to with 
my program. 

I started to wonder how the real programmers made tabs 
work. After all, both Edit and MacWrite do an admirable job 
of lining up columns of text. When I looked at Edit with a 
disassembler, however, my budding hopes were crushed. 
Someone had rewritten most of the TextEdit routines! I don't 
know if this gargantuan task was motivated principally by the 
need for tabs, but I was getting the idea that I might have a 
long road before me. 

The biggest reason tabs are so hard to implement is that 
they are variable-length characters. Sometimes a tab is only a 
character long, sometimes many. Its length depends on where 
it is located in a line of text (from the last CR). Widths of 
characters are normally looked up in a special table that is a 
part of every font record. Every TextEdit routine (minus 
TEInit, TENew, and TEDispose) makes use of character 
widths (e.g. TEActivate must calculate the selection rectangles 
between the selStart and selEnd character positions to 
highlight text properly). I half-heartedly started to code a 
custom implementation of TEClick, but I gave up. It's very 
complicated: calculating justification for each line, getting the 
clipRgns right, using the wordBreak routine, and trying to 
make sense of a lot of ROM code that just... doesn't seem to 
make sense. I'm not knocking Apple or their ROM code - far 
from it. After all, their thing was compactness, not logical 
layout to make code easy to read by hackers. Also they had to 
"get-it-done-NOW'", a motivating factor I've learned to have a 
lot of sympathy for since I've tried my hand at program 
development. Enough editorializing (I'll leave that to Ed). 
Suffice it to say that I felt that if there wasn't a way to use the 
standard TextEdit routines and still use tabs, my program 
wasn't going to have tabs. Somewhere, there must exist the 
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Elegant Solution (the programmer's elusive Holy Grail). 
Somehow, I had to intercept the routine that looked up 
character widths in the font record and modify it. That 
reminded me of something and I turned to page I-197 of IM. 

The grafProcs field of any grafPort can contain a pointer 
to a table of ProcPtrs that specify the low level routines which 
QuickDraw uses to (among other things) draw text and 
measure text widths. The standard routines to do these are 
called StdText and StdTxMeas, but their entries in the 
QDProcs record can be replaced with custom routines with the 
same arguments -- exactly what I needed. I wrote custom 
routines (first in TML Pascal, then in assembly for speed) 
which I call tabTxWrite and tabTxMeas. They work GREAT. 
Text lines up perfectly in columns. Any font (including 
proportional) works. Some windows can support tabs and 
others can use the standard QDProcs (since this is specified in 
each window's record). 

However, it isn't quite as simple is that. I didn't want the 
tabs to be equally spaced and I wanted each window to have 
different tabs. So I set up a tabRecord (see Type declaration in 
Pascal main program) and put a handle to it in the refCon field 
of each window. It contained mainly an integer specifying the 
number of tabs and an array showing where those tabs were 
(the pixel distances of the tabs from the left side of the 
destination rect). I made the tabs a resource. In the resource, I 
stored the tabs as a numbers of characters instead of pixel 
distances (they are converted when the window is set up), so 
that different size fonts would work the same. 

However, it isnt quite as simple as that. In addition to 
being variable-length, tabs have another peculiarity. Usually, 
when one tabs after the position of the last set tab in a line, 
the input caret skips to the beginning of the next line. In 
other words, such a tab is treated like a carriage return. I call 
such a tab, a pseudoCR. I cast around until I found a very 
good solution. There is a routine, scantily described on page I- 
391 of IM, called TERecal. All it does is recalculate the 
entries in the lineStarts array (the last field in the TErecord). 
Its address is stored in a low-memory system global (at $A74). 
It is called by many TE routines, but always indirectly 
through the address stored in $A74. I figure that the reason 
Apple used this scheme was so that we programmers could 
replace the address of the standard routine with a custom one. 
So that is what I did. Actually, I dug around until I found 3 
completely undocumented routines (see Table 1) which are 
called by TERecal and which are also accessed through low- 
memory system globals (and therefore, I feel, are fair game to 
replace). I wrote a replacement (tabLineStart) for the one in 
$7FC so that entries are inserted into the lineStarts array after 
every pseudoCR. So everything worked great. 


The subroutines below are always called by TE through the 
indicated low-memory global addresses. All of them expect to 
receive a pointer to a locked TErecord in A3. 


Table 1 


global Parameters 
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$7F8 input DO = a character position 
output: DO = char pos after 1st wordbreak char < DO 


D1 = char pos before 1st wordbreak char > DO 


$7FC input D6 = a character position 


output: DO = char position of next lineStart > D6 


$7F4 input D6,D7 = character positions 
output: DO = length of text from D6 to char pos 


just after 1st non-wordbreak char « D7 


Not quite. Unfortunately, it isn't even as simple as that. 
There are two problems. The low level text routines get 
passed only a pointer to text, and a count of the number of 
characters to measure or write. They know nothing about the 
TErecord they are writing into. In particular, they do not 
know where the beginnings of the lines are. Both of my 
custom routines ASSUME that the first character in the 
textbuffer is the beginning of a line. This is only a problem 
if the TE routines call the QuickDraw routines with 
textPointers to a character which is not a lineStart. That is 
the case, folks, at least on the 128/512K Macs (this has 
apparently been corrected in the new ROMs shipped with the 
Mac Pluses) For example, TEKey calls StdTxMeas three 
times: once for beginning of line to selStart - 8 (that's OK), 
once from beginning of line to selEnd (that's OK) and once 
from selStart - 8 to selStart (not OK). The extra characters 
that were erased and written were probably so that fonts with 
overlap between letters (kerning) would be written correctly 
(on the MacPlus, the -8 was changed to -1). So much for 
problem 41. The second problem is that some of the TE 
routines take action based on the presence of a CR, not just a 
lineStart, so they would not work when a pseudoCR was 
detected. The only solution is to replace every routine that 
causes problem #1 or problem #2. 

Fortunately, it turns out that the TextEdit routines call 
the low-level QuickDraw routines only indirectly via a built-in 
miniEditor (described briefly on page 1-391 of IM) whose 
address is stored in the low-memory system global, TEDoText 
($A70). This miniEditor is composed of four subroutines 
which variously hitTest (figure out which character position a 
Click is closest to), highlight a selection range, display some 
text, or position the pen to draw the blinking caret. Since 
these routines receive a pointer to the locked TErecord, it is 
easy. to find the beginnings of each line of text from the 
lineStarts field. The actions of the standard miniEditor can be 
changed by storing the address of a different miniEditor in the 
global, TEDoText. 

Either two or three of the miniEditor subroutines need to 
be modified to make our tabs scheme work, depending on 
whether the machine is a MacPlus or an earlier model. They 
are summarized in the accompanying Table 2. Once this is 
done, everything works correctly, from double-click text 
selection to un-backspacing tabs. It is that simple. 

The following subroutines in TEDoText need to be 
changed for the indicated reasons (Note the differences between 
the 512 and Mac+ ROMs) 
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Table 2 


Calls QD text routines w/ refers explicitly 


TEDoText textPtr in middle of line to CR 
Routines (Problem #1) (Problem #2) 
DrawSomeText . . — ----- ----- 
setCaret = -— 512/Mac+ 
HiLite 512 ----- 
HitTest 512 512/Mac+ 


A Few Intricacies (for those that like that sort 
of stuff) 


First of all, there are characters and there are inter- 
character positions. These are used rather loosely (such as IM 
talking about TEDoText hit-testing a character when actually 
it is looking for the inter-character position closest to the 
click). Characters are numbered from one to teLength. 
Character positions are numbered from zero (before the first 
character in the record) to teLength (after the last character in 
the record). LineStarts happen at character positions, They 
may be after regular characters (if the line was wrapped around) 
or after CRs (or pseudoCRs). In the first case, a click past the 
last character on one line or before the first character on the 
next line actually causes the HitTest routine to return the same 
character position. That is why there is an extra field (called 
clickStuff) in the TErecord, which must be set by the hitTest 
routine to tell the caret-placing routine whether to put the caret 
at the end of one line or at the beginning of the next (more 
about that below). Secondly, CRs (and pseudoCRs) are the 
last characters in their lines, not the 1st characters of the next 
line. This is actually quite significant. They have zero 
length, so that a click after them on the same line or at the 
beginning of the next line should, according to the above rule, 
cause HitTest to return the same character position. Of 
course, that would be wrong, since if the caret is at the 
beginning of the line, a backspace removes the CR (or 
pseudoCR) whereas if the caret is at the end of a line, a 
backspace removes the last (non-control) character. That 
means that, in this case, HitTest must specifically check for a 
CR (or pseudoCR) in front of the lineStart and return one less 
than it would if there was none. That is why the TEDoText 
hittesting routine had to be rewritten. 

Also, through some quirk, if a click occurs below the 
last line of the text, TEClick does not call the HitTest routine 
at all, but calls the setCaret routine with D3 equal to 
teLength. Poor setCaret cannot tell whether to put the caret at 
the end of the line or the beginning of the next line (since the 
clickStuff field was not set by HitTest). Therefore, setCaret 
must check to see if the last character in the record actually is 
a CR (or pseudoCR) and if it isn't, move the character to the 
end of the previous line. That is why the setCaret routine had 
to be rewritten. 

Here is some more information on the ClickStuff field, 
among others. In IM, eight fields of the TextEdit record are 
marked {used internally} with no further explanation except 
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their names and the warning, "Don't change any of the fields 
marked “used internally". Although I don't claim these to be 
definitive, here is some idea of what they do: 

active -- High byte: set if window active. Low byte 
always 0. 

Time (in tics from startUp) when last click 
happened (used to check for double clicks). 
Result of last call to HitTest subroutine = 
character position of click (used to check for 
double clicks and when click-drag is specifying 
a range). 

Time when next caret toggle should take place. 
High byte: set if caret visible (alternates as 
caret blinks). Low byte: set if caret should 
blink (would be zero if selStart + selEnd, i.e. a 
selection range). Note: these are called teCarOn 
and teCarAct in the new versions of the Apple 
MDS equate files. 

Absolutely nothing. 

Absolutely nothing. 

High byte: set by HitTest, if last click was at 
first character position of a line (as opposed to 
last character of previous line). Low byte: set 
if caret should be shown in front of 1st char of 
line (as opposed to after last character of 
previous line). Note: these are called 

teLftClick and teLftCaret in the new versions 

of the Apple MDS equate files. 


clickTime -- 


clickLoc -- 


caretTime -- 
caretState -- 


recalBack -- 
recalLines -- 
clickStuff -- 


Description of Pascal tabEditor Program 


The editor program presented has been stripped of most of 
its features to emphasize the tab feature and to save room. 
Therefore, it does NOT save, print, resize, scroll, or allow 
multiple windows. Most of these features have been described 
before or could be more conveniently (and clearly) described in 
a separate column and all of them can be added modularly on 
top of the tabEditor program without rewriting any existing 
code. TabEditor DOES handle desk accessories (including 
cut/paste) and puts up an About... dialog. It allows one to 
exit the program, via the File/Quit menu. It opens a textEdit 
window into which text can be typed, cut, copied, pasted, or 
cleared and which furthermore, has tabs set every 8th character 
position. If the window is closed with its close box, a New 
window can be opened using the File/New menu. 

The code in tabEditor's Pascal listing which deals 
explicitly with the tab feature is boldfaced and consists of a 
few lines in the Initialize routine which are executed once, a 
few lines in the Activates and Updates subroutines, and the 
entire subroutine SetUpForTabs, which is called once for each 
window supporting tabs at the time of its creation with 
GetNew Window or NewWindow. 

Initialization Code, TabEditor also requires six global 
variables, which are all set by the Initialize. myQDProcs is a 
QDProcs record as described on page I-197 of IM, and is filled 
with pointers to all of the standard low-level QD routines by 
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SetStdProcs. Then two of the pointers are changed to point to 
the custom text routines, tabTxMeas and tabTxWrite. 
nowTabs contains a handle to the tabRecord (defined under 
Type) of the current window or NIL if the current window does 
not support tabs. globalA70 is a long integer pointer: i.e., it 
is set to point to the long integer at absolute address $A70. 
Note that the standard pointer type would not work since it 
points to a byte and we need to address the whole long integer 
(i.e. ptr^ is length 1 byte, while LIptr^ is length 4). We 
change the address of the miniEditor used by ROM routines 
through this global variable. The address originally stored in 
$A70 is saved in stdEDoText during the initialization process, 
for two reasons: 1) This routine is called via this application 
global from the tabTEDoText assembly routine. 2) I also 
restore the default miniEditor address to $A70 when leaving 
the program, although this is unnecessary since ExitToShell 
restores it anyway. global7FC and stdLineStart function in 
the same way as globalA70 and stdTEDoText. However, it is 
absolutely necessary to restore the default address (in 
stdLineStart) to global $7FC upon exiting the program since 
ExitToShell does not (otherwise the next program to call this 
routine will crash). 

Activates Code, Whenever a window deactivates, the 
nowTabs application global must be set equal to NIL (so that 
a desk accessory, for example, will function correctly). It must 
be set to the handle of the tabRecord (if there is one) when a 
window activates. Both tabTEDoText and tabLineStart check 
if this global is NIL and passes control directly to the default 
routine if it is. 

Whenever a window updates, the 
nowTabs application global must be set equal to the tabHandle 
of the window being updated, since it may not be the same as 


the active window. That means that the nowTabs handle of 
the active window must be saved and restored after the update 
is done. 

This subroutine gets passed a 
windowPointer and a resource ID. The window must already 
have been created, and must have a handle stored in its refCon, 
which points to a block containing only the handle of the 
window's TErecord. The resource ID must be for a resource of 
type bTAB' (I use the same resource ID as for the window 
itself) which contains the tab information. The block 
containing the TEhandle is enlarged with SetHandleSize so 
that there is enough room for the Tabs array. Then the 
resource information is copied to the tabRecord with a 
BlockMove. Note that although the tabRecord type definition 
allows up to 100 tabs per line, an actual tabRecord is a 
dynamic structure with only enough space allocated to hold the 
array of tabs contained in the resource. Finally, the character 
position of each tab in the tabRecord is multiplied by the 
width of the zero character to convert it to a pixel length. 
Also, as a time-saver, the standard pixel width of the tab 
character is stored in the tabRecord to be used by the 
tabTxMeas routine (this width is taken directly from the font 
character-width table and usually equals the width of a space). 


Description of tab Resource 
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The 'bTAB' (arbitrary and non-registered) resource 
contains integers: the number of tabs followed by the character 
position of each tab. Note that it can be edited by any 
resource editor to change the position of the tabs or to 
add/remove tabs. 


Description of Low-level QuickDraw Text 
Routines 


TabTxMeas is my replacement for the standard QD text 
measuring routine, StdTxMeas. It starts by measuring the 
given text using StdTxMeas which gives a pixel length (D7), 
which we will have to modify only if there are some tabs in 
the text. Then it checks each character to see if it is a carriage 
return (CR) or tab. If it is a CR, it sets a pointer to point to 
the character after the CR (A3), and zeros a character counter 
(D6) and zeros D5, which is the pixel length from the 
beginning of the line to A3. If it is a tab, it first subtracts off 
the standard tabwidth (from the nowTabs record). Then 
StdTxMeas is used to measure the pixel length of the text 
from A3 for D6 characters (this text contains by definition no 
CRs or tabs) and this length is added to D5 (which now makes 
it the pixel length from the beginning of the line up to the 
tab). If D5 is greater than the last tab position or if lastTab is 
Zero, then the tab is treated exactly like a CR. Otherwise, the 
tab position just larger than D5 is added to D7 and D5 is 
subtracted from D7 (i.e. D7 increases by the width of the tab 
character alone). Then DS is set equal to the tab position, A3 
is set to point to the character after the tab, and D6 is zeroed 
(making everything consistent). 

labTxWrite looks up destRect.left for the TErecord 
whose handle is stored in nowTabs and stores it in D7. It then 
checks each character to see if it is a tab. If it encounters a 
tab, it writes all characters (counted by D6) since the character 
just after last tab (pointed to by A3) using StdText. Note that 
the pen is positioned by StdText just after the last character 
written. tabTxWrite puts the horizontal pen position (via 
GetPen) into D5, and subtracts off D7 to get the pixel width 
of the characters since the beginning of the line. If D5 is 
greater than the last tab position or if lastTab is zero, nothing 
is done. Otherwise, DS is subtracted from the tab position 
next larger than D5 and the pen is moved by that amount. 
When all characters have been checked, StdText is called one 
more time to write all remaining characters. 


Description of LineStart Calculating Routine 


tabLineStart receives a character position in D6 and must 
return the next larger lineStart position in DO. It initializes 
D4 equal to the width of the destRect and D7 equal to D6. 
Inside the Loop, the routine whose address is in $7F8 is called 
with DO equal to D7. It returns the position before the next 
wordbreak character (i.e. D7 is incremented by one word). If 
the CR only field of the TErecord is zero, the text width from 
D6 to D7 is calculated (via routine whose address is in $7F4) 
and compared to D4. If the text has exceeded the end of the 
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destination rectangle, a lineStart is placed one larger than D5, 
which is what D7 was last time through the loop (one word 
back). If this is the first time through the loop (i.e. we're still 
working on our first word), D5 is undefined, but that's OK 
because A2 (the word counter) = 0, so we are detoured through 
oneWord, which is a code fragment that backs up the end of 
the single word, one character at a time, until it has enough 
characters to just fill the width of the destRect. There it 
inserts a lineStart. If the text has not exceeded the end of the 
destRect (or CRonly is nonzero), the wordbreak character at 
D7 is checked to see if it is a CR (or pseudoCR) and, if so, a 
lineStart is returned. Note that a lineStart is also returned if 
we reach teLength before anything else. 

An aside I found interesting. IM states that TEDoText 
and TERecal receive a pointer to a locked TErecord in A3 and 
that is true. However, whenever more lineStarts need to be 
added to that TErecord, its size must increase, as necessary, to 
accommodate them. This means that a subroutine called by 
TERecal can unlock the TErecord, move it elsewhere, and 
relock it. Therefore one must be careful in making copies of 
A3 or pointers to other fields in the TErecord. A2 (used as a 
pointer to somewhere in the lineStarts array) is however 
adjusted by the subroutine to point to the same position in the 
moved record. 


Description of MiniEditor Text Routines 


TabTEDoText is called by the TextEdit routines to do 
basic editing. If nowTabs is NIL or D7 = -1, control is passed 
immediately to the default miniEditor. Otherwise, if D7 is 0 
or -2, tabTEDoText calls the custom routines, HitTest or 
setCaret, respectively. Since the Hilite routine is needed on 
128K/512K machines and not on MacPluses, it is 
conditionally compiled depending on the state of the 
ROM128K flag. On  MacPlus, if D7- 1, tabTEDoText 
calls the default miniEditor. For earlier machines it calls 
HiLite. (Note that Hilite will work on the MacPlus also). 

HitTest receives the point where the mouse was clicked 
in local coordinates in the selPoint field of the TErecord. 
TEClick has already processed the vertical component of that 
point by the time that the miniEditor is called, so that the 1st 
character position of the line containing selPoint is in D3, and 
the 1st character of the next line (or teLength) is in D4. All 
that remains for HitTest to do is to find out which character 
position between D3 and D4 is closest to selPoint.h. First, 
selPoint.h minus destRect.left is moved to D7. If this is less 
than zero (i.e. selPoint is to left of first character in the line) 
then D3 is returned in DO and clickStuff is set. Otherwise D4 
is adjusted to point to the last character in the line (rather than 
the 1st character in the next line). This is the only part of the 
program which had to be different from the default hit-testing 
routine so that tabs (actually pseudoCRs) would work. D6 is 
set equal to D4 minus D3 (number of characters in the line). 
The width of the D6 characters is calculated (D5), compared to 
D7, and D6 is decremented. If D7 is greater than D5 the first 
time through the loop (i.e. the selPoint was beyond the last 
character in the line) the position of the last character in the 
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line is returned in DO. Otherwise the loop continues until 
D5 < D7 < D4 where D5- D3«D6 and D4=D5+1. D4 
minus D7 is compared to D7 minus D5 to see which character 
position is closest. 

A few words about speed. The standard hit-testing 
routine in the default TEDoText on the 128/512K Macs, uses 
TextWidth on each single character in the line (creating 
problem #1 -- see above), adding them up to compare to 
selPoint.h. This is probably faster than the method used in 
HitTest and the new 128K ROMs, which call TextWidth the 
same number of times, but for strings of characters rather than 
single characters. Both the intrinsic 512K and MacPlus hit- 
testing routines use PtInRect to see if selPoint is in selRect, 
which is set using the same routines used for highlighting, I 
think this was done to use existing code, rather than for speed. 
HitTest isn't appreciably slower than the standard routine, 
although I haven't tested it on very large text files. HitTest 
could probably be speeded up by changing it to check character 
positions from the beginning of the line to the end, or by 
calculating single character widths and adding, unless a tab 
character is detected. 

HiLite receives the character positions of the start/end 
select range in D3/D4. If D3 equals D4, HiLite does 
absolutely nothing (except set AO equal to thePort as specified 
by the description of TEDoText in IM. I don't know why this 
is necessary, and the more adventuresome of you might want 
to leave it out). If D3 is larger than D4, the registers are 
exchanged because the default miniEditor does that, although I 
doubt that HiLite is ever called with D3>D4 (TEClick 
makes the adjustment before calling the miniEditor if you 
click-drag select text from a high character position to a low 
one), so this could probably be left out. HiLite proceeds to 
calculate rectangles one line at a time, which are in turn 
processed by subHilite. The first line rectangle must have a 
left side equal to the destRect.left plus the textWidth of all the 
characters from the first character of that line to D3. The last 
line rectangle gets its right side set in a similar fashion using 
D4. Any in-between rectangles have to be as wide as the 
destRect. Note that HiLite sets these lefts and rights to $8002 
and $7FFE, which are one short of minus and plus machine 
infinity. I do this because the default routine does it, and 
because I ran across at least one place elsewhere where these 
values were checked for explicitly. If D3 and D4 are in the 
same line, only one rectangle needs to be inverted, a 
combination of the first and last rectangles. 

A loop in HiLite gives (A2) < D3 < 2(A2). Note that 
D3 cannot equal teLength. Then each rectangle described 
above is calculated in the selRect field of the TErecord. 
subHilite either calls InvertRect or the HiHook routine (see 
IM page I-379), if there is one. 

I left out a routine (at $41668E on the MacPlus) that 
changes D3/D4 so that they correspond to lines actually inside 
the viewRect. I don't think that this makes for an upDate 
problem since the text is clipped to the viewRect anyway, but 
it would speed up the HiLite routine if there was a LOT of 
selected text not in the viewRect. Adding this routine is left 
as an exercise for those who need it. 
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SetCaret receives the character position of the caret in D3 
and sets selRect to be one pixel wide and lineHeight tall in the 
proper location. It is very straightforward unless D3 happens 
to be equal to a lineStart. In that case, the clickStuff field is 
checked to see if the caret should be put at the end of the line 
or at the beginning of the next line UNLESS D3 is equal to 
teLength. In that case, as explained previously, the last 
character in the record is checked to see if it is a CR (or 
pseudoCR) and, if not, the caret is put end of the previous 
line. 


Once the mysteries of text handling on the Mac are 
understood, implementing tabs is pretty straightforward. 
Making tabs setable from the program is not too difficult. 
Just add Print, Save, Scroll, Size, a few menus to change the 
overall TErecord font and textSize, and a search/replace 
routine, and you have a fullblown text editor. 


Program TabEditor; 


( Pascal source: tabEditor Pas > tabEditor.rel 
assembly source: tabGlue.asm > tabGlue.rel 
Resources: tabEditor.R > taebEditor/RSRC.rel) 


($T APPL BRAD } 

($8* set bundle bit ) 
($I MemTypes.ipas } 
($1 QuickDrew.ipas ) 
($1 OSIntf.ipas ) 
($1 ToolIntf.ipas ) 
($U tabGlue) 

($L tabEditor/RSRC ) 


CONST 
applemenu= 391; 
filemenu = 302; 
editmenu = 303; 
windID = 300; (our text window) 
eboutID = 3090; {modal dialog) 
TYPE 


tabRecord = RECORD 
tebTE: X TEHandle; 
tebWidth: integer; 
lastTab: integer; 
Tabs: array (1..100)] of integer; 


END; 
tabPtr = ^tabRecord; 
tebHendle = “tabPtr; 
LIptr = “LongInt; 
VAR 

done: boolean; 
nyWindow: WindowPtr; 
nowTE : TEHandle; 
nowTabs: tebHendle; 


textCursor: cursHandle; 
DragArea: Rect; 
stdTEDoText: LongInt; 

stdL ineStart: LongInt; 
globslA70:  LIPtr; 
global7FC:  LIPtr; 
myQDProcs:  QOProcs; 


FUNCTION tabTxMeas(byteCount: integer; textAddr: Ptr; VAR 


numer,denom: Point; VAR info: FontInfo): integer; EXTERNAL; 
PROCEDURE tabTxWriteCbyteCount: integer; textBuf: Ptr; 
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numer ,denom: Point); EXTERNAL; 
PROCEDURE tabTEDoTExt; EXTERNAL; 
PROCEDURE tablineStart; EXTERNAL; 


(xxx xke initialization Procedures XEXXtXtÓXrrtrtxrkx) 


———— ————————— M ) 


PROCEDURE SetUpForTabs(resID:integer; wPtr: windowPtr); 
Var 


eHnd1 , resHnd] : handle; 

tabH: tebHendle; 

i,widthZeroCher: integer; 

bTABsize: longInt; 
Begin 


eHndl:- HendleCGetWRef ConCwPtr 2); 
resHndl:» GetResource( 'bTAB' ,resID); 
bTABsize:s GetHandleSize(resHndl); 
(make rel block large enough to hold rest of tebRecord) 
SetHendleSizeCeHndl,bTABsize + 6); 
tabH:= tabHendleCaHnd!2; 
(set tebWidth field of tabRecord) 
tebH^^ . tabWidth:= CharWidth(Chr($9)); 
(transfer rest of tabRecord) 
BlockMove(resHnd1*,@tabH**. lastTab, bTABSize); 
ReleeseResource(resHnd1); 


widthZeroChar := CharWidth(Chr($30)); — (width of a zero ) 
WITH tebH^^ DO 
if lastTab o Ø then 
for i:= 1 to lastTab DO (transform tabs from * chers ) 
Tabs[iJ:= tabslil*widthZeroChar; (to pixel lengths) 


wPtr* .grafProcs:= @myQDProcs; 
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PROCEDURE SetupMenus; 

Ver MenuTopic: MenuHandle; 

Begin 
MenuTopic := GetMenuCAppleMenu); (get the apple menu) 
AddResMenu(MenuTopic, 'DRVR'); (adds all 'DRVR's) 
InsertMenuCMenuTopic, 8); (put in menuBer) 


MenuTopic := GetMenuCFileMenu2); (Quit & New) 
Inser tMenuCMenuTopic, 2); 


MenuTopic := GetMenuCEditMenu); 
InsertMenuCMenuTopic, 8); 


DrawMenuBar ; 


FUNCTION SetUpTextWindowCID_No: integer): WindowPtr; 


ver 

Hndl: Handle; 

r: Rect; 

li: LIptr; 
myW: windowPtr; 
&TE: TEhendle; 


Begin 
myW := GetNewWindowCID.No, NIL, POINTERC- 12); 
SetPor tCmyW); 


r:* myW^.portRect; 
WITH r DO begin top:= top + 4; left:= left + 4; end; 
aTE:= TENew(r,r); 


Hndl:» NewHandleCord4(4)); 


1i:= LIPtrCHnd1*); 
1i*:= ord4CaTE); 
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SetWRefConCmyW, ord4CHnd12); 
(nyW refCon has handle to a relocatable block ) 
{containing only a TEhandle for the moment) 


SetUpForTebsCID. No, myW); 
(should be called once for every new window Supporting tabs) 
SetUpTextWindow:s myW; 
End; 


PROCEDURE Initialize; 


var 
i: integer; 
r:  Rect; 


Begin 
Init6ref CéthePort); 
InitFonts; 
InitWindows; 
InitMenus; 
TEInit; 
InitDialogs(Nil); 
FlushEventsCeveryEvent, 2); 


(create a grafport for the screen) 


r:= ScreenBits.Bounds; 
SetRect(Dragdrea,r.left+4,r.top+24,r.right-4,r.bottom-4); 
done := FALSE; (set by QUIT command to signal end) 
SetupMenus; 


myWindow := SetUpTextWindow(windID); 
nowTabs := tebHendleCGetWRef Con(myW indow)); 
nowTE:s nowTabs^^.tabTE; 


textCursor := GetCursor(ibeamCursor); 
HLockCHandleCtextCursor 2); 
InitCursor; (show the Arrow cursor) 


globalA70:- LIptr($A7@); (global variable points to TEDoText) 
stdTEDoText:= globalA7Q"; 

(save pointer to default miniEdit routine) 
globalA70^:- ord4(@tabTEDoText); 

(set so calls to miniEdit go to our modified tab routine) 


global7FC:= LIptrC$7FC); (global var points to lineStart) 
StdlineStart:= global7FC-; 

(save pointer to nonTab lineStart routine) 
Qlobal7FC*:= ord4(@tablineStart); 

{set so calls to lineStart routine go to modified tab routine} 


(set up a special QOprocs record for use with tab windows) 
SetStdProcs(myQDProcs); 
myQDProcs. txMeasProc:= étabTxMeas; 
myQDProcs.textProc:= @tabTxWrite; 

End; 


(*xxxxt***** Menu Command Processing **#**xxx} 


PROCEDURE ProcessMenu(CodeWord: longint); 


Var 
i,Menu_No, (menu number selected) 
Item. No: integer; (item in selected menu) 
NameHolder: Str255; (for desk accessory) 
DNA: integer; (dummy return) 
ourD1g: dialogPtr; 

Begin 


If CodeWord <> Ø then 

BEGIN (process the command) 
Menu.No := HiWord(CodeWord); 
Item.no := LoWord(CodeWord); 


CASE Menu_No of 
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AppleMenu: if Item no = 1 
then begin — (About...) 
ourD1g:= GetNewDialog(AboutID, NIL, POINTERC-12); 
ModalDialog(NIL, i); 
DisposDialogCourD19); 
end 


else begin (Desk Accessor ies) 
GetItemCGetMHandleCApp leMenu), Item. No, NameHolder ); 
DNA := OpenDeskAcc(Nam ieHolder); 
end; 


FileMenu: CASE Item No OF 
1: begin 
myWindow:= Setl ipTextWindow(windID); (NEW) 
nowTabs:- tabHtindleCGetWRef ConCmyWindow)) j 
nowTE:- nowTab:s^^.tabTE; 
DisableItemCGe tMHandle(FileMenu), 1); 


end; 
2: done:= TRUE; (Q JIT} 
end {CASE}; 


EditMenu: 
If Not SystemEditCItem_no - 1) then 
CASE Item. No OF 
1: ; (undo) 
(2: line divider) 
3: TECutCnowTE); 
4: TECopyCnowTE); 
9: TEPesteCnowTE); 
6: TEDeleteCnowTE); 
end (Item. No CASE); 


(for DAs) 


End (Menu_No CASE); 
END (if); 


HiliteMenu(@): 


(unhil' ite after processing menu) 
End; | (ProcessMenu) 


(*****XX* Event Processing Ro utines X*rxxexaee) 


PR oe hoes ee ee a E ) 
PROCEDURE MouseDowns(Event : Ev 'entRecord); 
Ver 
WindowPointedTo: WindowPtr ; 
MouseLoc: Point; 
WindoLoc: integer; 
Begin 


MouseLoc := Event.Where; 
WindoLoc := FindWindow(Mou seLoc, WindowPointedTo); 
CASE WindoLoc OF 


inDesk: (empty statement); 
inMenuBar: ProcessMenu(Men uSe lect (MouseLoc)) A 
inSysWindow : SystemClick(E vent., WindowPointedTo); 
(desk accessor ies) 
otherwise if WindowPointed To <> FrontWindow 
THEN SelectWindow(Window PointedTo) 
ELSE CASE WindoLoc OF 
inContent : 
BEGIN 
Global ToLocal (Mou se'. oc); 
TECTick(MouseLoc, CEjitAndCEvent modifiers, shif tKey) 
= shif tKey),nowTE); 
END; 
inGrow: (empty statement); 
inDrag: 
DragWindow(Windo wPointedTo, MouseLoc, DragArea); 
inGoAway : 
If TrackGoAway(W ‘indowPo intedTo, MouseLoc) then 
begin 
TEDisposeCn owTE); 
DisposHandl eChandleCnowTabs)); 
nowTabs:s MIIL; 
DisposeWinc jow(WindowPointedTo); 
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EnebleItemCGetM HendleCF i leMenu), 1); 


end; 
END (CASE); 
End (CASE); 
End (MouseDowns); 


PROCEDURE KeyDowns(Event :Eventk'ecord); 
Var CharCode: char; 
Begin 
CharCode := chr(bitAnd(Even t.message, charCodeMask )); 


If BitAndCEvent .modifiers,Cmdk ey) = CmdKey 
then ProcessMenu(CMenuKey(Cha rCode )) 
else TEKey(CharCode, nowTE); 


End (KeyDowns); 


(mmm ) 
PROCEDURE Activates(Event: EventR ecord); 
Var 

TergetWindow: WindowPtr; 


active: boolean; 
eHndl: handle; 


Begin 
TargetWindow := WindowPtr(Event.i nessage); 
active:= OddCEvent.modifiers); 

(true = the window is becoming act ive} 


IF active THEN 
begin 
SetPortCTargetWindow); 
nowTabs:- tabHandle(GetWRefCoi ^CTargetWindow2); 
nowTE:= nowTabs^^.tabTE; 


TEAct ivateCnowTE); 

end ELSE 

begin 
TEDeActivateCnowTE); 
nowTabs:= NIL; 

end; 


End (Activates); 


PROCEDURE Updates(Event:EventRecord); 

Var 
UpDateWindow, 
savePort: WindowPtr ; 

tempTabs: TabHandle; 

Begin 
UpDateWindow := WindowPtr(Event .mes: sage); 
GetPort(savePort); (Save thie current port) 
tempTabs:= nowTabs; (Save current. tebsHandle) 
SetPort(UpDateWindow); (set the port. to one in Evt.msg) 
nowTabs:= tabHendle(CGetWRef ConCUjpDa: LeWindow2); 
BeginUpDateCUpDateWindow?; 
EreseRectCUpDateWindow^ .VisRgn^^ .rgnBBox?; 
with nowTabs** DO TEUpdateCtabTE:^^ .. viewRect, tabTE); 
EndUpDateCUpDateW indow); 
SetPort(CsavePort); 

port) 
nowTabs:= tempTabs; 

End (Updates); 


(txtxx iXX x End of Event Processing KEXKEKEKEKEE) 


( www ee ee ee = = ) 


PROCEDURE MainEventLoop; 
Ver 
Event:EventRecord; 
mousePt: Point; 


(rest;ore to the previous 


(restore to current tabHandle) 
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(regular keyboard entry) 


Begin 
Repeat 
SystemTask; (run Desk Accessories) 
if myWindow = FrontWindow then 
begin 
Ge tMouse(MouseP t ); 


if PtinRectCMousePt ,nowTE**.viewRect) 
then SetCursor( textCursor**) 
else SetCursorCarrow); 
TEIdleCnowTE); 
end; 


If GetNextEventCEveryEvent,Event) then 
CASE Event.what OF 


mouseDown: MouseDowns(Event); 
KeyDown, autoKey: KeyDowns(Event); 
ActivateEvt: Activates(Event); 
UpDateEvt: Updates(Event); 


END (CASE); 
Until done; {terminate the program) 
End; 


BEGIN (Main Program} 
Initialize; 
MainEventLoop; 
globalA7@* := stdTEDoText; 
global/7FC*:= stdlineStart; 
END (TebEditor). 


4 


j tabGlue 


Note: Hilite is not needed for the Mac Plus because some 


,Shortcomings of the TEDoText routines have been rectified in 


j the new 128K roms. If you have a MacPlus, set the constant 
;R0M128K equal to 1. If you have a 128K/512K Mac, 


; set it equal to Ø. The appropriate parts will be assembled. 


i INCLUDES -------------------- 


Include MacTraps.D ; Use System and ToolBox traps 
Include ToolEqu.D ; Use ToolBox equates 


j---------- XDEFs & XREFs --------- 


XDEF — tabTxMeas ; replaces stdTxMeas 

XDEF — tabTxWrite  ; replaces stdText 

XDEF  tabTEdoText ; replaces TEDoText in $A70 
XDEF  tabLineStart ; replaces lineStart in $7FC 


QUEE global variables ----------------- 
; the address of the default TEDoText routine was saved 
; in this application global during main program init 


XREF — stdTEdoText ; address of standard routine 
XREF — stdLineStart ; address of standard routine 
XREF — nowTE ; currently active TEhandle 
XREF nowlabs ; current tabRecord handle 

¿C or Ø if not tab Window) 


; conditional assembly of Hilite routine if not set 
ROM 128K EQU 
; so I don't have to load the QuickDraw Equates 
left — EQU2 
bottom EQU 4 
right EQU6 
; Offsets into tab record 
tebWidth EQU 4 
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lastTab EQU 6 

TABS EQUS8 
; Note: clickStuff (1 word) is now teLftClick & teLftCaret 
; (bytes) 


a a ta Other XDEFs --------------------- 

; XDEF all labels to be symbolically displayed by debugger . 
; these are the names of custom replacements for 3 of the 4 
,routines called by TEDoText. 


XDEF setCaret 

XDEF HitTest 
IF ROM128K © 1 

XDEF HiLite 
ENDIF 


a a tabTEdoText ------------------- 


4 
f A3?) pointer to locked edit record 

; M?» handle to edit record 

; UD3» position of 1st char to be drawn or selected 

; D4» position of last char to be drawn or selected 

;, DT» Ø to hit-test a character 

: 1 to highlight the selection range 

^ -] to display the text 

: -2 to position the pen to draw the caret 

; on exit: 

, A0» pointer to current grafPort 

; DO» if hit-testing, character position (-1 for none) 
d 


é 

tabTEdoText 
TST.L nowTabs(A5) ; if not a tabWindow 
BEQ eo ; go to default routine 
TST D7 
BEQ = HitTest ; D =Ø 

IF ROM128K © 1 
BPL HiLite ; D7 = 1 

ELSE 
BPL eg 

ENDIF 
CMP 8-1,D7 


BLT setCaret ; D7 = -2 
@ð MOVE.L stdTEdoText(A52,A8 ; D7 = -1 
JMP (A2) 


foc ero setCaret --------------------- 
, on entry:see above 


) 

; Other variables 

, A2» pointer to lineStart < D3 

exit: 

; M = thePort on exit as mandated by Inside Macintosh 
; SelRect encloses caret 


J 
setCaret 
MOVEM.L D2/D6/D7/A2,-CSP) 
LEA teLines(A3),A2 
TST D3 
BEQ E2 
eg CMP 2(A22,D3 
BLS e1 
ADDQ 82 A2 
BRA eo 
@1 CMP 2(A22,D3 ; (A2) < D3 < 2(42) 
BNE E2 
ADDQ 82 ,A2 ; now D3 = (A2) 
MOVE teLength(A3),D0 
BEQ E2 
CMP D£,D3 
BCS EO 


; from here to EØ executed only if D3 = teLength(A3) 
MOVE.L teTextHCA3), A 
MOVE.L CAB), Ad 
; if D3 = CR, don't put caret on previous line 
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CMP.B 8$D, - 1(A0,03) 
E2 


BEQ 
MOVE -2(A2),D6 
MOVE D3,D7 
SUBQ 81,D7 
JSR tstTab itreat pseudoCR (tab) like CR 
BEQ E2 
BRA E1 
; teLftCaret is set if caret is at beginning of line 
EO TST.B teLf tCeretCA3) 
BNE E2 
E1 SUB 82,A2 
, Set top and bottom of selRect 
E2 LEA teL inesCA3), A0 
SUB .L A2,A0 | 
MOVE AO, DØ 
NEG DØ 
ASR #1,DØ ; divide by 2 
MOVE teLineHiteCA3),D1 
MULU D1,08 
MOVE.L teDestRect(A3), teSelRect(A:32; top and left 
ADD DØ, teSelRect(A3) 
MOVE teSelRect(A3), teSelRect*bot tom(A3) 
ADD D1, teSelRect*bottomCA3) 
; Set left and right of selRect 
MOVE.L teTextHCA3), Ad 
MOVE.L CAB), AB 
CLR -(SP) 
MOVE.L A0,-CSP) ; textBuf 
MOVE (A2)2,D0 
MOVE D0,-C(SP) ; firstCher 
MOVE D3, -CSP) 
SUB DØ, CSP) 
-TextWidth 
MOVE (SP)*,DO ; length of text from (A2) to D3 
ADD DØ, teSelRect*lef tCA3) 
MOVE teSelRect*leftCA3), teSelRect*r ight(A3) 
ADDQ 8], teSelRecttright(A3) 


; return 
MOVEM.L (SP )+,D2/D6/D7/A2 
MOVE.L CA5), AO 
MOVE.L CAD), AG  ; AG = thePort CI don't know why) 


j rteeewessegedeu HitTest ----------------------- 
; on entry:see above 
;  teSelPoint field has mousePt in local coord 
, 03> first char in line 
» D> first char in next line 
; Other variables 
» D> flag & hiPosition 
; D5» loPosition 
; D6>> counter of char position in line 
; Uh?  selPoint.h - destRect. left 
; A2? pointer to locked hText 
, on exit: 
; M = thePort on exit as mandated by Inside Macintosh 
, D» cher position of "hit" character 
HitTest 

MOVEM.L A2/D4-D7, - CSP) 


CLR.L D6 ; clear bit 31 to save Lock Bit 
MOVE.L teTextHCA3),A2 

BSET 87 (A2) 

BEQ e0 

BSET #31,D6 ; Save Lock Bit 


@ð MOVE.L CA2), A2 
CMP .B #$D,-1CA2,D4) 
e1 


BEQ 
MOVE.L —— A2,A0 
MOVE D3,D6 
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MOVE 
SUBQ 
JSR 
BNE 
81 SUBQ 


62 MOVE.L 
SUB 
BGT 
MOVE 
BRA 


@3 MOVE 
SUB 
CLR 

loop 
MOVE 
CLR 
MOVE.L 
MOVE 
MOVE 
~TextWidth 
MOVE 
CMP 
DBGE 


ADD 
MOVE 

; if = 6 (i.e. 
TST 


BEQ 
SUB 
SUB 
CMP 
BLE 
ADDQ 


StopHT 
TST.L 
BMI 
MOVE.L 
BCLR 


eg CMP 
SEQ 
MOVE.L 
MOVE.L 
MOVEM.L 
RTS 


IF ROM128K © 1 


; on entry: 


D4,07 

#1,D7 

TstTab ; check if pseudoCR 

e2 

#1,D4 ; for CR or pseudoCR (tab) 


teSelPoint (A3), D7 
teDestRect *lef tCA32,D7 
e3 

D3,D0 

StopHT 


D4, D6 
D3,D6 
D5 


point.h 
; relative xPosition 


; flag for ist time thru loop 


D5,D4 ; save high position 
-(SP) 

A2,-CSP) ; teTextH pointer 
D3,-CSP) ; firstChar 


D6,-CSP? 

CSP)+, DE; 

D5,D7 

D6, loop  ; drops thru when D5 <= D7 < D4 
D3,D6 ; convert to absolute char position 


D6,D0 

selPoint.h > end of line) then you're done 
D4 

StopHT 

D7,D4 

D5,D7 

D4,D7 

StopH T 

#1,D0 


D6 ; restore Lock Bit 
eo 
teTextHCA32,A2 
87, CA2) ; clear Lock bit 

D3,D0 

teLf tClickCA3) ; click at beginning of line 
CA5 ), Ad 

CAO ), AO ; thePort 

CSF')+ ,A2/D4-D7 


; assemble if 128/512K Mac 


- HiLite --------------------------- 


see above 


' other variables: 
D5>> ]ineHeightCA3) 


| exit: 


pointer to lineStarts 


A8 = thePort on exit as mandated by Inside Macintosh 
; preserves ell but A0,D0 


J 
J 
4 
P] 
; A2» 
4 
4 
é 


ed LEA 
@1 CMP 


teL inesCA3), A2 
A2,D0 
2(A22,D3 


@2 MOVE.L A2,01 
SUB D9,D1 
; D1 is offset of line containing D3 from lineStarts 


; CA2) «s D3 < 2(42) 


LSR #1,D1 ; divide by 2 to give * lines 
MOVE teL ineHi teCA3),D5 

MULU D5,D1 

MOVE.L teDestRectCA3), teSelRectCA3) 


ADD D1, teSelRectCA3) ;TOP of 1st rect 
MOVE teSelRectCA3), teSelRect*tbottomCA3) 

ADD D5, teSelRect*bottomCA3) ; BOTTOM 

MOVE S$7FFE,teSelRecttright(A3)  ; RIGHT 

CLR -CSP) 

MOVE.L teTextHCA3), Ad 

MOVE.L (A02,-CSP) 

MOVE (A2),D0 

MOVE D ,- (SP) 

MOVE D3, -CSP) 

SUB DO, CSP) 

-TextWidth 

MOVE (SP)+, DØ 

ADD DØ, teSelRect+lef tCA3) ; LEFT of 1st rect 
CMP 2(A22,D4 

BLE LastRect 


JSR SubHilite ; INVERT Ist rect 
; LEFT of subsequent rects 


MOVE  #$8002, teSelRect+lef t(A3) 


@5 ADD D5,teSelRect(A3) ; TOP of subsequent rects 
ADD — D5,teSelRect*bottom(A3); BOTTOM 
ADDQ — "2,42 


CMP 2(A2),D4 
BLE LastRect 


JSR SubHi lite ; INVERT middle rects 


BRA e5 
LastRect 

BE eo 

CLR -(SP) 

MOVE.L teTextHCA3), AQ 

MOVE.L (A0), -CSP) 

MOVE (A22,D0 

MOVE DØ, -CSP) 

MOVE D4, -CSP) 

SUB DØ, CSP) 

_TextWidth 

MOVE (SP )+,D8 

ADD teDestRect* lef tCA32,D0 

MOVE DØ, teSelRecttright(A3)  ; RIGHT of last rect 
ed JSR SubHilite ; INVERT last rect 
StopHL 

MOVE.L (A52,A0 

MOVE.L CAB), AB ; thePort 

MOVEM.L CSP +, A2/D3-D5 

RTS 
ae a a SUGHI] 106; eec eee ee eEeEne ce 
; if hiHookCA3) # Ø, jumps to it. Otherwise inverts 
selRectCA3) 
subHilite 

PEA teSelRectCA3) 

MOVE.L teHiHook(A3), Ad 

CMP.L "Q AQ 

BEQ eg 

JMP (A0) 
60  InverRect 

RTS 


ENDIF ; conditional assembly of HiLite routine 
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4 
d 


tablineStart ----------------------- 


pointer to locked edit record 


A4,A6>> used by subroutines (don't change) 


D6>> 


; on exit: 


4 
) 


DO») 


char position (usually lineStart) 


next lineStart > D6 


jothers variables: 


eg 


e2 


A2» 
D5»» 
D6»» 
D7»» 


* words in line 

pixel length of lest tab 

Ist char of current line 

last char of current line 
subroutines: 


in $7F4returns DØ = length of text from D6 up to last 
nonWordBreak char « D7 

in $7F8 returns D1 = char position before ist 
wordBreak char > DØ 


TST.L 


MOVEM.L 
MOVE 


MOVE 
MOVEM.L 
RTS 


oneWord 


SUB 
MOVEM.L 
MOVE.L 
JSR 
MOVEM.L 
CMP 


nowTebs(CA5) ; if not a tab Window 

eg execute default routine 
stdLineStart(A5), Ad 

CAG) 


D1-D7/A1/A2, -CSP) 
teDestRect*r ightCA32,D4 
teDestRect*lef t(A3),D4 


81,D4 

A2,A2 ; Clear A2 to use as counter 
D6,07 

D7,D0 

1$C,D2 

$7F8,A40  ; jumps to routine 

(A0) ,Whose address is in global 7F8 
D1,07 ; increment D7 by one word 
teCrOnlyCA3) 

eo 

D6/D7,-CSP) 

$7F4,A0 ; jumps to routine whose 
CAB) ,address is in global 7F4 
(SP +, D6/07 

o ; if 2 width destRect, put lineStart 
D7,D5 

#1,A2 ; increment word counter 


teLengthCA3),D7 


endLS , if at text end, put in lineStart 
teTextHCA3), Ad 

(A02, AD 

“$FFFF D7 

*$0,CA0,D7.L) ; if = CR, put in a lineStart 
e2 

tstTab ; if = pseudoCR, lineStart 

62 

#1,D7 ; Otherwise look at next char 
LSloop 

A2,D0 ; if > than 1 word fits in destRect 


oneWord ; branch to fitting routine 


D5, D8 
(SP )+,D1-D7/A1/A2 


; if one word > than the line, break it anyway 
#1,D7 


D6/07 ,-CSP) 


$7F4, AG ; jumps to routine 

(A0) ; whose address is in global 7F4 
(SP )+,D6/D7 

DO, D4 ; take off 1 char at a time until 
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BLE oneWord ; word fragment fits in destRect 
MOVE D7,D5 
BRA endLs 

Qj ARAE tebTxMeas ------------------------- 


;FUNCTION tebTxMeas(byteCount: integer; textAddr: Ptr; VAR 
;  numer,denom: Point; VAR info: FontInfo): integer; 


CLR -(SP) 22*24 room for result 
MOVE byteCount, -CSP) 20*24 

PEA text 16424 

PEA numer, -CSP) 12+24 

PEA denom, -CSP) 8+24 

PEA fontinfo 4+24 

JSR tabTxMeas 

A2>> ptr to current char 


A3)? ptr to char right after last CR or TAB 
D3>> . tabWidth 

D4>> counter of all char 

D5>> textwidth from last CR to present 


TAB Cnot inclusive) 
D6»» of char since last CR or TAB (not inclusive) 
D7»» length of all text 
81] registers preserved except A0,D0 


tebTxMeas 
MOVEM . L A2-A3/D3-D7 , -CSP) 
MOVE 48(SP),D4 ; byteCount ** 
MOVE.L 44(SP2,A2 ; textPtr ** 
MOVE.L nowTabs(CA5), Ad 
MOVE.L CAG), AO 
MOVE tabWidthCAg),D3 
MOVE .L A2,A3 
CLR D5 
CLR D6 
CLR -CSP) 
MOVE D4, -CSP) 
MOVE.L A2,-CSP) 
MOVE.L 48(SP),-(SP) ; numer ** 
MOVE.L 48(SP),-(SP) ; denom ** 
MOVE .L 48(SP),-CSP) ; fontinfo ** 
-StdTxMeas 
MOVE (SP?*,D7 ; length of all text 
SUBQ 81,D4 ; UBxx counter 
Chk CR 
CMP.B 813, (A20* ; if char = CR, then 


BNE ChkTAB 


CLR D5 ; clear LengthSinceLastCR 
BRA bothCRandTab 
chkTAB 
CMP.B 89,-1(A2) ; is char = TAB? 
BNE endLoop 
SUB D3,D7 
; Width of tab put D7 in by StdTxMeas 
CLR -(SP) 
MOVE D6, -(SP) 
MOVE.L A3, -CSP) 
MOVE.L 48CSP), -CSP) ; Numer ** 
MOVE.L 48(SP),-CSP) ; denom ** 
MOVE.L 48CSP), -CSP) ; fontinfo *x 
-StdTxMeas 
ADD (SP)*,D5 
MOVE.L nowTebsCA5), Ad 
MOVE.L CAD), AB 
MOVE lastTabCAd), DØ 
BEQ bothCRandTab 
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; ignore if no tabs set (this is a pseudoCR!) 


SUBQ 
LEA 


ed CMP 


DBLT 
BGE 


#1,D8 
TABSCAG) AD 


; convert to DBxx counter 


CAS)+,05 
Dd, ed 
bothCRandTab 


; branch if we are past last tab, i.e. ignore it (this is a 


pseudoCR! ) 


ADD 


-2(A0),D7 


; adding pixel width of line including new tab to D7 
SUB 


05,D7 ; pixel width of line up to new tab 

MOVE -2CA02,D5 ; new linewidth including new tab 
bothCRandTab 

MOVEQ #-1,D6 

MOVE.L A2,A3 
endLoop 

ADDQ #1,D6 

DBF D4, chkCR 

MOVE D7,50CSP) ; answer ** 

MOVEM.L CSP )+, A2-A3/D3-D7 

MOVE.L (SP), Ad 

ADD %$16,SP 

JMP (A0) 
aaa aca tebTxWrite ----------------- 


“PROCEDURE tabTxWrite(byteCount: integer; textBuf: Ptr; 


numer ,denom: Point); 


MOVE byteCount, -CSP) 16+24 
PEA text 12+24 
MOVE.L numer ,-(SP) 8+24 
MOVE.L denom,-(SP) 4+24 
JSR tabTxWrite 


A2)» ptr to current char 

A3>> ptr to char right after last TAB 

D4>> counter of all char 

D5»» length of text up from last CR 
to present TAB Cnot inclusive) 


D7>> teDestRect. left 
A®,D8 not preserved 


Wwe We ee We We We We We We We We We We We We BD 


D6>> number of char since last TAB (not inclusive) 


MOVE.L SP, -CSP) 
-GetPen 
MOVE.L (SP)*,D5 ; horiz position in low word 
SUB D7,D5 ; length of text from zero position 
MOVE.L nowTabs(A5), Ad 
MOVE.L CAD), AD 
MOVE lastTabC AS), DØ 
BEQ endLoop. ; ignore tab if none are set 
SUBQ 5] D0 ; convert to DBxx counter 
LEA TABSCA0), AD 
ed CMP (AQ)*,D5 
DBLT T, 
BGE endLoop. ; branch if we are past last tab 
MOVE -2(AB) , DB 
SUB D5, D8 
MOVE DO ,-CSP) 
CLR -(SP) 
-Move 
endLoop. 
ADDQ #1,D6 
DBF D4, chkTab. 
MOVE D6,-(SP) ; write all chars since last tab 
MOVE.L A3,-CSP) 
MOVE.L 38CSP),-CSP)  ; numer ** 
MOVE.L 38CSP2,-CSP)  ; denom ** 
-StdText 
StopTO 
MOVEM.L (SP)*,A2-A3/D4-D7 
MOVE.L CSP), Ag 
ADD #$12,SP 
JMP (A0) 
pesce Eee US C180 Roc CE C EO 


AQ»? ptr to hText buffer 

char position of 1st char in line 
D7>> test char position 

; sets Zbit of CC if char not pseudoCR (tab) 

; preserves all registers except A2,D0,D1 


4 
tabTxWrite 
MOVEM.L À2-A3/04-D7 ,-CSP) 
MOVE 40CSP2,D4 ; byteCount ** 
SUBQ #1,D4 ; make DBxx counter 
MOVE.L 36CSP), A2 ; textPtr ** 
MOVE.L A2,A3 
CLR D6 
MOVE.L nowTECA5),A9 ; handle to TErecord 
MOVE.L CAO), AD 
MOVE 2(A0),D7 ; GestRect. left 
chkTab. 
CMP .B 89 CA2)+ 
BNE endLoop. 


; write all chars since last tab 


MOVE 


D6, -CSP) bytecount 


MOVE.L — A3,-CSP) : ptr to text 

MOVE.L 38(SP),-C(SP)  ; numer ** 

MOVE.L 38(SP),-CSP)  ; denom ** 

-StdText 

MOVEQ #-1,D6 ; reset counter 

MOVE.L A2,A3 ; text ptr points at char after tab 
CLR.L -(SP) 
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tstTab 
CMP.B "$9, (A0,D7) ; if = TAB 
BNE eo 
CLR -(SP) 
MOVE.L Ad, -CSP) 
MOVE D6, -CSP) ; firstChar 
MOVE D7,-CSP) 
SUB D6, CSP) ; byteCount 
-TextWidth 
MOVE (SP)*,DO ; length of text from D6 to D7 
MOVE.L nowTabs(A5), A0 
MOVE.L CAB), AB 
MOVE lastTabCA@),D1 
LEA TABSCA2), AD 
ADD D1,D1 
CMP -2(A0,012,D0 
SLT DØ 
; if DØ < lastTab position, return NotEqual 
TST.B 
ed RTS 
END 


Dr. Nedrud wins $50 and our thanks 
for this extension to TextEdit, as 


this month's outstanding article. 
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tebEditor /RSRC.re1 


Type BRAD = STR 
g 


Bradley W. Nedrud 


Tgpe FREF 
300 


APPL Ø 


Type BNDL 


, 300 
BRAD 
ICN" 

0 300 
FREF 

0 300 


Type ICN! = GNRL 
,900 (32) 
H 


1FFFFOOO 
1000 1000 
1000 1000 
16DB 1000 
100 18040 
10023007 
1000 1FE7 
00000000 
x 


1FFFF OOO 
IFFFFOOO 
1FFFFOOO 
1FFFFOOO 
1FFFFFCO 
1FFFFFFF 
1FFFFFFF 


1088 1000 
1000 1000 
16DB 1000 
1000 1000 
10023020 
100 10007 
1099 10 1F 
00000000 


1FFFF OO 
1FFFF OOO 
IFFFF OOO 
1FFFF OOO 
1FFFFFEO 
IFFFFFFF 
1FFFFO IF 


Version 8.1 May 31, 1986. 


1000 1000 
16DB 1090 
1000 12900 
1020 1F 00 
16DFC8 18 
19008007 


16DB 1020 
1000 1900 
1090 1900 
16DB6080 
1004 7F OF 
10006007 


IFFFFOO7 00000000 
00000000 00000000 


IFFFF OO 
iFFFFOO 
1FFFFOOO 
1FFFFFOO 
IFFFFFFØ 
IFFFFFFF 


1FFFFOOD 
1FFFFOOD 
IFFFFO00 
IFFFFF80 
IFFFFFFF 
IFFFFFFF 


IFFFFOOT 00000000 


00000000 00000000 00000000 00000000 
TYPE MENU 

,301 

14 
About tabEditor... 


,902 
File 
(New/N 
Quit/Q 


TYPE WIND 
*DrawWindow 


s 
New 


38 67 293 450 
Visible GoAway 
Ü 


“j 

TYPE DLOG 

*about dialog 
, 300 


90 58 250 450 
Visible NoGoAway 
1 
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0 
300 


TYPE DITL 
*for About Dig Ø Ø 200 400 
300 


s 


button 
170 220 190 300 
OK 


Statictext disabled 
58 20 78 390 


tabEditor, a simple Pascal Editor Supporting tabs 


Statictext disabled 
80 100 100 360 
written by B. W. Nedrud - May 1986. 


statictext disabled 
115 128 135 360 
€ 1986 by Nedrud Data Systems 


*tabs for myWindow 

TYPE bTAB = GNRL 
,900 

.I 

5 

8 16 24 32 40 


IPAS$Xfer 


/Globals -4 
tabEditor 
PAS$Library 
OSTraps 

ToolTraps 

tabGlue 

/Resources 
tabEditor /RSRC 
/Bundle 

, we ‘APPL’ 'BRAD' 
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Programmer's Forum 
Notes From TML To LSP 


For a while it seemed if you wanted to do any 
programming in Pascal on the Mac, you must either bear the 
cost of a Macintosh and a Lisa to do any serious 
programming, or you could always use MacPascal. Neither 

was an acceptable solution. Those with larger bank accounts 

could afford two machines but that was unacceptable for most 
of us. MacPascal was also unthinkable since it does not 
generate compiled code, but like most interpreters it is easier 
to develop code than the compile/link method. 

Enter TML Pascal. When TML came onto the scene 
about a year ago, there were nothing but raves about the 
product. I was ecstatic when I started using it myself. The 
only capability that seemed to be missing was the ability to 
compile and link separate units. For many of us this was not 
a problem, as it was promised in a further release. So we all 
continued to develop our programs, and except for the units 
problem continued to rave about the program. How can you 
put down a product that measures up to equivalent compilers 
(C, Forth and Fortran) that cost three, four and five times as 
much. But as our programs got larger, compile times got 
longer and there was still no units capability. Four or five 
changes and compiles could take an hour or more. 

Wouldn't it be nice to have the capabilities of both TML 
and MacPascal to do our development! And LightSpeed Pascal 
comes as close to this as I believe you are likely to see. I 
found I was developing code in hours that would have taken 
me days or weeks to do under TML. 

This is not a review of LightSpeed Pascal, but an 
impression of the program I have from having used both TML 
and LightSpeed. I will be showing you some of the 
differences between the two development systems and some of 
the problems I encountered in my experience with the new 
program. It is important to note that these tests are run on a 
old 512K Mac with the old Roms and 400K drives. 

First of all, for those of you who are currently using 
TML and wish to convert to LightSpeed, you will find the 
conversion very easy. The first step is to change the compiler 
directives. In your TML source you may have some lines 
similar to the following: 

($1 MemTypes.ipas } 
{$1 QuickDraw.ipas ) 
{$I OSIntf.ipas } 

{$I Toollntf.ipas ) 
{$1 Packlntf.ipas } 
{$a+} 

{$L Grow/Rsrc } 

These lines need to be removed and replaced with 
{SI-} 

{$R-} 
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The first line "{$I-}" tells the compiler that you don't 
want LightSpeed to do automatic initialization. You should 
always put this in your code or else the program may work 
when running in project mode and may not work when the 
code is converted into an application. The second line "{$R-}" 
tells the compiler you want range checking off. This is only 
necessary if you have this line in your TML code or you don't 
have the range checking option defined at all. This is because 
LightSpeed defaults to range checking on and TML defaults to 
range checking off. If you have range checking off in TML 
and range checking on in LightSpeed, code that worked under 
TML may not work under LightSpeed. 

Second, if you are using a resource file, you must remove 
the ".REL" extension from the ".R." file and change it to 
anything else so that RMaker does not compile the resource 
file in REL format. LightSpeed suggests ".RSRC", but in 
actuality any extension or no extension will do. You must 
declare something, however, or RMaker won't compile the 
file. Then you run RMaker to create the new resource file. 
Next you must tell LightSpeed about the resource file by 
selecting "Run Options” from the Project menu. When the 
dialog box appears, check the resource box and choose the 
resource file to use (if you haven't converted the resource file 
from the REL format, the file won't appear). 

Third, if you have your comments on multiple lines 
surrounded by only two curly braces you will get an error. 
For example: 


{this comment section 
must be changed} 


which works in TML, must be changed to 


{this comment section} 
{must be changed} 
for the code to work in LightSpeed. 


This was all that was necessary to get my old TML code 
running under LightSpeed. My program is a terminal 
emulator for a Data General which uses multiple windows 
(text and drawing) and does file transfers. It currently is about 
1200 lines long. I used this program for my testing and also 
the famous Sieve program to do comparisons between the two 
compilers. 

The relative speeds and sizes are compared in the 
following tables. As can be seen from the tables, the 
application programs are larger (about 2k) in the LightSpeed 
versions. I talked to the LightSpeed people about this and 
apparently the program does a certain amount of 
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routine stripping to keep the application to a reasonable size. 
The TML stripping linker is a little better (my application 
was 14K under TML version 1.0 and 8K under 1.1). Routines 
you reference may cause LightSpeed to pull in related routines 
even if they aren't used. This is apparently a tradeoff for 
speed. 2K seems to be close to the maximum difference 
between from TML and LightSpeed as can be seen from the 
graphs and tables. 

The development speeds reflect the time it takes to make 
changes and and execute the programs. As can be seen you 
can make a change and test it in less than a minute (about 30 
seconds if not saving the text). In TML this would take about 
5 minutes - five to ten times longer. 

The Sieve program has been used in benchmarks of other 
compilers and I decided to use it to compare these two. The 
code I used was: 


PROCEDURE EXECUTE_SIEVE; 
CONST 


SIZE = 8190; 
VAR 
FLAGS : ARRAYIO..SIZE] OF BOOLEAN; 
I, PRIME, K, COUNT, ITER : INTEGER; 
TEXTSTRING : STR255; 
BEGIN 
GOTOXYCIO, 10); 
DRAWSTRINGC'19 ITERATIONS. PRESS MOUSE WHEN READY TO G0!'); 
REPEAT 
UNTIL BUTTON; 


FOR ITER := 1 TO 50 DO (THIS IS USUALLY 1 TO 10) 


BEGIN 

COUNT := Ø; 

FOR I :- Ø TO SIZE DO 
FLAGSLI] := TRUE; 

FOR I := Ø TO SIZE DO 
IF FLAGSEI] THEN 
BEGIN 


PRIME := i + i + 3; 
(gotoxy( 18, 12);) 
(ERASE_LINEC12, 10, 19);} 
(nuntostring(prime, textstring);) 
(DRAWSTRINGCTEXTSTRING); ) 
k := i + prime; 
WHILE k <= size DO 
BEGIN 

flags(k] := false; 

k := k + prime; 
END; 
count := count + 1; 


END; 

gotoxy( 18, 14); 

ERASE_LINEC14, 10, 15); 
numtostring(count, textstring); 
drawstring(textstring); 

gotoxy( 15, 14); 
drawstringC'primes'); 


4 


4 


It was rather interesting that if you display the prime 
numbers as they are found, TML seems a little faster and when 
the numbers aren't displayed LightSpeed seems a little faster. 
It seems that LightSpeed's computations are a little better but 
TML's handling of QuickDraw may be a little faster. 

I would liked to have compared the units capability of the 
two compilers, except as of this writing, it was not available 
on TML. It is now released as version 2.0. 
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Some notes on LightSpeed: 

Type cohersion cannot always be done within a procedure 
or a function statement. According to LightSpeed the rule is: 
if the variable in the procedure is a "var" parameter you cannot 
use type cohersion; if not a "var", you can. They say it is a 
high priority to make this more like Lisa Pascal by removing 
this restriction. 

You cannot get the assembler source like you can in 
TML. This may be a problem if you want to optimize a piece 
of code. This is apparently not a high priority item with 
them. It would also be a little more difficult to do, according 
to them, because the compilation doesn't go through the 
normal "compile to assembler source" and then assemble that 
code. They go directly from Pascal source to machine code. 

Segmentation is handled differently. LSP requires 
segmentation at unit boundaries, while TML allows the 
segment option to be placed directly in the code. Also, LSP 
uses all the space in the first segment for it's libraries so that 
your main program must be limited to about 5K in the first 
segment, with everything else in units placed in the second 
segment. Yet when the application is built, your program may 
fit entirely within segment one. Thus our 14K program 
required two segments with only a 5K main in segment one. 

LSP also does not have objects and LS is moving slow 
on this. TML on the other hand supports objects in 2.0. 

All in all, I was very impressed with the product and had 
no problems with it, once I found out about the range 
checking, REL resource and curly brackets differences. I think 
there is going to be less of a demand for MPW with this 
around. 


ELATIVE PROGRAM SIZES (Bytes)TML LightS peed 
1200 Line Program 9758 11988 
1000 Line Program 8022 10164 
600 Line Program 4744 7448 
Sieve Program Display 3348 4235 
Sieve Program No Display 3298 3340 
RELATIVE PROGRAM SPEEDS 
Sieve Program TML LightSpeed 
Compiled-10 iterations w/ display 93.50 95.00 
Compiled-10 iterations w/o display 6.85 6.50 
Compiled-50 iterations w/display 446.30 471.40 
Compiled-50 iterations w/o display 33.40 30.50 
Not Compiled-10 iterations w/ display 228.20 
Not Compiled-10 iterations w/o display 53.20 
DEVELOPMENT SPEEDS TML LightSpeed 
Editor to Execution(1000 lines&savetext) 290.00 55.00 
Editor to Execution(samelines;don'tsavetext) 251.00 34.00 
Execute Emulator (compiled) 25.00 25.00 
Execute Emulator (project) 34.00 
Execute (Go) if no changes 8.00 
Execute (Go) after change & changes are saved 35.00 
Execute (Go) after change & changes not saved 34.00 
Build New Application and Execute 184.00 
Start Project and Open Source File zw 55.00 
Start Project, open source file, Execute ETA 86.00 
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MacApp Objects 
Dots Game Introduces MacApp 


An Introduction to MacApp 


Edit 


Larry Rosenstein 
Product Engineer, MacApp 
Apple Computer, Inc. 


Dots 


Suppose you just got a great idea for a new — E 
Macintosh™ application. Regardless of whether — | 10 | 
it deals with music, animation, or (even) word f 
processing, one task you face is developing the 
particular features of your program. After all, 
these features are what you — and it is hoped 
your users — are most interested in seeing on 
the screen. 

On the Macintosh, users also judge 
applications by their interfaces. In order for your 
program to be accepted, it should follow the user 
interface guidelines as closely as possible. 
Unfortunately, the more time you spend 
implementing the user interface, the less time 
you can devote to the exciting (musical, 
graphical, etc.) parts of the application. 

To help solve this problem, a group at Apple®, which 
included me, developed an application framework called 
MacApp.'M MacApp automatically implements the standard 
features of a Macintosh application, which allows you to 
concentrate on the unique parts of your program. 

For example, MacApp completely handles moving and 
resizing windows, scrolling, printing, and displaying error 
alerts. MacApp also provides a general design for other 
features such as Undo and document filing that make it much 
easier to implement these features. 

In this article I want to first describe the basics of object- 
oriented programming, which helps make MacApp possible, 
and the overall MacApp architecture. Then I will describe a 
small game program written using MacApp. 


Object-Oriented Programming 


It is difficult to explain object-oriented programming in 
only a few paragraphs. Our experience with brand new 
MacApp programmers is that it takes a couple of weeks for 
them to understand object-oriented programming and feel 
comfortable using it. So, don't worry if you don't grasp the 
concepts right away. What is object-oriented programming 
anyway? 

Object-oriented programming is a way of writing 
programs. Conventional (that is, non object-oriented) 
programs are organized around a set of data structures, and 
procedures or functions that manipulate those data structures. 
For example, MacDraw'M represents graphical shapes by a 
variant RECORD type in Pascal, and implements routines to 
draw, stretch, save, etc. these records. Each of these routines 
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Fig. 1 Complete Mac Game in Two Days 


uses a CASE statement to distinguish the different kinds of 
shapes and perform the appropriate action for each. 

Object-oriented programs, however, are organized around a 
set of object types. Each object type defines both data 
structures, or fields, and methods that operate on the fields. 
An object definition, therefore, is much like a RECORD 
definition in standard Pascal. 

The methods implemented for an object are the only 
routines that modify the object’s fields. (Although Object 
Pascal does not enforce this restriction.) The process of 
calling a method is often called message passing. The 
programmer creates a set of objects and sends them messages. 
When an object receives a message, it decides what action to 
take (i.e., what method to execute). Different objects can 
respond to the same message in different ways. 

Object-oriented programming also involves the concept of 
inheritance. This means that one object type can be derived 
from an existing object type. A derived type inherits all the 
behavior (fields and methods) of the base type. It can, 
however, override any method it chooses. 

For example, I could define a Rectangle object type that 
implements 2 methods: Draw, which calls FrameRect to 
outline the rectangle, and ComputeArea, which returns the 
rectangle's area. 

Later, someone else could define a subtype called 
ShadedRectangle that is derived from my Rectangle object. 
ShadedRectangle would override the Draw method and call 
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FillRect with a particular pattern. Since the area of a shaded 
rectangle is the same as that of an empty rectangle, the 
ShadedRectangle object type can inherit my ComputeArea 
method. (In Figure 2, you see that both Rectangle and 
ShadedRectangle share the implementation of ComputeArea.) 

Because ShadedRectangle was derived from Rectangle, it 
inherits all the behavior of Rectangle. Any piece of code that 
deals with Rectangle objects can also deal with 
ShadedRectangle objects without change. 


If MacDraw were written using object-oriented 
programming, it might define a generic Shape object type. 
Shape objects would define the methods that all shapes must 
implement, for example Draw, Stretch, Save, etc. There 
would also be specific object types, derived from Shape, such 
as Rectangle, Oval, Text, etc. (The Oval object type could 
also be derived from the Rectangle type, since ovals and 
rectangles differ only in the Quickdraw procedures used to draw 
them.) 

The value of object-oriented programming is evident 
when you start modifying a program. Suppose you wanted to 
add triangle objects to MacDraw. In a conventional 
programming methodology, you would have to add a new 
variant to the MacDraw shape RECORD type, and modify 
each of the routines that deal with shapes so that they handle 
triangles. 

With object-oriented programming, adding a triangle 
shape would involve creating a Triangle object type, which 
would be derived from the generic Shape object type, and 
implementing the methods Draw, Stretch, Save, etc. The 
main part of the program, which just sends messages to shape 
objects, does not have to change at all. 

Notice that all these changes are localized in the definition 
of Triangle, rather than scattered throughout the program. 
Also, since the main part of the program does not change at 
all, it is possible to add new kinds of shapes without 
recompiling the rest of the application. In fact, you don’t even 
need the sources; you can simply link in the modules 
containing the new object types. 


MacApp Basics 


MacApp consists of a set of object types. The MacApp 
objects themselves implement most of the standard features of 
Macintosh applications, such as window resizing. You can 
compile MacApp right out of the box and get a fully- 
functional Macintosh application that doesn’t do anything. 

To write your application you define object types that are 
derived from the standard MacApp objects and override any 
methods you choose. To use MacApp, you generally deal 
with the following five object types: 


(1) TApplication, which handles the top-level control 
structure and main event loop of your program. It also 
handles global commands (Open..., Quit, etc.) and creates 
TDocument objects. 
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Method Implementation 


Rectangle Object m 


ShadedRectangle Object 


ComputeArea 


Figure 2 


(2) TDocument, which contains the data used in your 
program, and provides methods for manipulating the data. 
It is also responsible for reading and writing the data to 
disk, and creating TView and TWindow objects. 


(3) TView, which draws your data on the screen, and 
processes mouse clicks. 


(4) TWindow, which represents a Macintosh window that can 
move, resize, and scroll. 


(5) TCommand, which represents an undoable action in your 
program. It is responsible for performing an action as 
well as undoing it. 


When you write a program using MacApp, you generally 
define new object types derived from TApplication, 
TDocument, TView, and TCommand. In most applications, 
the standard TWindow type defined in MacApp is sufficient. 


Dots 


The best way to understand how MacApp works is to 
look at a sample program. Rather than choosing one of the 
samples that comes with MacApp, I wrote a simple game 
program from scratch. (This game took about 2 days to 
implement and debug.) 

The game of Dots begins with a matrix of dots. Two 
players take turns drawing horizontal or vertical lines to 
connect any two adjacent dots. Whenever a player draws a line 
that completes a square, that player claims the square - in the 
paper version, by writing his initials inside. The one with the 
most squares is the winner. 

A screen shot of the game is shown in Figure 1. In my 
version of the game, the players take turn clicking on a line 
with the mouse. Each player is represented by a 
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different pattern, and the program takes care of filling in 
squares with the appropriate pattern as they are completed. It 
also keeps track of the score and inverts the score of the player 
whose turn it is. 

The first thing I did to implement the Dots program was 
think about the object types I needed and the methods each 
needed to implement. Because of the MacApp architecture, I 
knew immediately that I needed subtypes of TApplication, 
TDocument, and  TView (called  TDotApplication, 
TDotDocument, and TDotView). To display the current score, 
I needed another view object, called TScoreView. Finally, I 
needed a TDotCommand object, so that a player’s move could 
be undoable. 

Several of the methods I needed to implement were 
required by the architecture of MacApp. For example, 
TDotView and TScoreView both needed a Draw method to 
draw the game board and score respectively, and 
TDotDocument needed a DoRead method to read saved games 
from the disk. 

Each object type also needed methods specific to my 
particular application. For example, TDotDocument 
implements methods for marking and erasing lines in the grid. 
TDotView and TScoreView implement methods for 
invalidating parts of the views, which are called by the 
TDotDocument. 

Next, I needed a way to represent the state of the game 
and refer to lines and boxes on the grid. I decided to name each 
line in the grid according to: (1) the dot at its left or top end 
and (2) its orientation (horizontal or vertical). Whether or not 
the line is drawn or erased is recorded in the fLine field of the 
TDotDocument, which is simply a 3-level array of Booleans. 
Similarly, the state of each box is represented in the fBoxes 
field of my document object. 

The only methods that access these fields directly are in 
TDotDocument (GetLineState, SetLineState, and 
ChangeBoxState). Hiding the representation of the grid in this 
way allows me to easily change the implementation of 
TDotDocument without affecting the rest of the program. 

Once I defined the internal representation of the game, I 
then defined the appearance of the game on the screen. This is 
done in the Draw method of TDotView. The Draw method 
simply loops for each dot and calls another method, 
DrawCorner. DrawCorner is responsible for drawing a dot, 
any lines leading from the dot to the right or bottom, and the 
box to its bottom right. The important point to note here is 
that DrawCorner uses the methods of TDotDocument to find 
out the state of the lines and box. 

The other main function of TDotView is to handle mouse 
clicks. This is done by its DoMouseCommand method. 
DoMouseCommand simply creates a TDotCommand object 
and returns it to MacApp. (What happens to the commands 
object is described below.) 

You will notice from the listing that TDotView also 
implements several methods that deal with visual 
representation of the game. For, example, the method 
Pt2Line converts a point within the view into a specification 
for the line at that point. 
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The TScoreView object provides a different view of the 
game. It simply summarizes the current score and indicates 
whose turn it is. In MacApp, it is possible to have several 
views of the same document. 


TDotCommand serves 2 purposes. First, it tracks the 
mouse while the player is choosing a line. Recall that 
DoMouseCommand creates a TDotCommand object and 
returns it to MacApp. MacApp then enters a loop that calls 
methods of TDotCommand as long as the user holds the 
button down. 

There are three such methods. First is TrackFeedback, 
which simply highlights the line at which the user is currently 
pointing. 

The second method is TrackConstrain. This method is 
called to give the application a chance to modify the actual 
mouse coordinates. In a graphical application, for example, 
you would implement gridding using this method. In my 
case, I use this to eliminate flashing when the user moves the 
mouse but still points to the same line. 

The final method is TrackMouse. TrackMouse is called 
each time through MacApp's loop to report the current mouse 
position. MacApp also tells the command object if the mouse 
has moved, and automatically scrolls the document if the user 
moves the pointer outside the window. 

In my program, TrackMouse simply waits until the user 
releases the button. Then, it figures out which line, if any, 
the user selected. If the user doesn't select any line, 
TrackMouse returns the special command object gNoChanges, 
which tells MacApp that nothing happened. In other cases, 
however, it returns itself, which tells MacApp what action to 
perform. 

After TrackMouse exits, MacApp takes the return value 
and (assuming it is not gNoChanges) calls the DoIt method of 
that command. The command object responds to DoIt by 
drawing a line in the grid by calling 
TDotDocument SetLineState. 

MacApp also saves the command object away, in case the 
user picks Undo from the menu. If that happens, MacApp 
calls the UndoIt method of the same command object. The 
command object then erases the line with another call to 
SetLineState. (If the user picks Undo again, MacApp calls the 
RedoIt method of the command.) 


There are a couple of things to note about this program. 


First, it has many features that are not obvious from 
looking at the listing, because they are implemented in 
MacApp itself. You can move, resize, scroll, and print the 
game window. If you click the mouse in the grid and drag 
outside the window, the grid automatically scrolls (assuming 
that the entire grid is not already showing). You can open 
multiple game windows at once. The game implements Save, 
Save As..., Save a Copy..., and Revert command. 

Second, this simple program does some things that some 
commercial programs don't do at all. For example, it displays 
detailed error messages describing what went wrong. For 


O The Complete MacTutor, Vol. 2 


example, if you try to save a game to a locked disk, you will 
see the message “Could not save the document because the 
disk is locked. Eject the disk and move the write-protect tab.” 

The important thing to realize is that I did not write a 
single line of code to implement these features: they were all 
inherited from the standard MacApp code. The 2 days it took 
to implement this application is typical of the time needed to 
get an application up and running (once you know the basics 
of MacApp, of course). 

There are tradeoffs in using MacApp. If you want to 
implement a non-standard user interface, you may have to 
override several MacApp methods. In general, however, the 
code you would write is the same as if you were to implement 
everything from scratch. 

My Dots program ended up being 63,996 bytes after I 
compiled it without debugging code and with the optimizer 
tool. That space broke down as follows (approximately): 


1044 method tables 
3722 application code 
3768 program jump table 
3834 MacApp initialization code 
5550 other resources 
21404 MacApp resident code 
24674 MacApp non-resident code 


Remember that this application has more features and 
better error handling than the typical sample program. Also, 
the space required by MacApp is essentially constant: in a 
commercial application it would be a small fraction of the 
total application size. 


I am sure that had I written Dots from scratch, it would 
have been smaller. On the other hand, it would not have as 
many features and I would not have finished it in time for 
MacTutor’s editorial deadline! 

Had I not used MacApp and Object Pascal to implement 
the Dots game, I probably would have used a standard 
RECORD structure to save the game state, and would have 
implemented most of the same utility routines to manipulate 
the game. Since MacApp imposes no restrictions on the 
internals of your program, it can be written in standard Pascal, 
C, or assembler. (It is possible to write and debug the internal 
algorithms in a system such as Lightspeed Pascal,™ for 
example, and convert the Pascal code into MPW Pascal once it 
works completely.) 

The performance of a MacApp application is comparable 
to that of an application written from scratch. There is a 
slight performance penalty for the method calls, but MacApp 
comes with a method call optimizer that removes this penalty 
from many method calls. We have made a lot of performance 
improvements between the beta releases and the final release, 
especially in the area of text handling. (I was able to write a 
MacPaint-like application in MacApp that was very close to 
the real MacPaint in speed.) 

MacApp does not relieve the programmer of the task of 
writing efficient code. For example, my Dots progam draws 
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the entire grid every time the Draw method is called. I could 
speed up scrolling significantly by changing TDotView.Draw 
to only draw the elements that need to be updated. The area 
parameter to Draw indicates the bounding box of the area that 
needs to be refreshed. MacApp includes performance 
measurement tools so that you can find out where your 
application’s inefficiencies are. 

Apple doesn’t expect everyone to use MacApp. Most 
programmers who have already implemented a Macintosh 
application have probably developed their own personal 
framework, similar to MacApp, and will continue to use it. 
MacApp is intended primarily for the programmers who have 
not yet implemented an application, and don't want to learn all 
the intimate details of Inside Macintosh. 

One significant benefit of using MacApp is that you can 
take advantage of the expertise and work that went into its 
design. In developing MacApp, we have tried to find the best 
way to accomplish a particular task (e.g., memory and 
segment management) and incorporate it into MacApp. Even 
before you write a line of code, you are starting with a library 
that has 2 years of testing and development behind it. 

Just remember one of the mottos of the MacApp team: 
"We do the programming, so you don't have to!” 


Apple is a registered trademark of Apple Computer, Inc. 
Macintosh, MacApp, MacDraw are trademarks of Apple 
Computer, Inc. Lightspeed Pascal is a trademark of Think 
Technologies. 
IPC 
PROGRAM Dots; 

(* Main program of the Dots game. 

Written by Larry Rosenstein, Apple Computer 
CSNet: 1sr&Apple.CSNET 
n UUCP : (Sun, nsc) apple! Isr 


($L0AD MacIntf.LOAD) 
MemTypes, QuickDraw, 
OSIntf, ToolIntf, PackIntf, 

($LOAD UMacApp.LOAD) 

UObject, UList, UMacApp, 

($LOAD) 

UPrinting, UDots; 
VAR 
das daa TDotApplication; 
(Initialize the ToolBox; MacApp will call 
MoreMasters 8 Hines.) 

InitToolbox(8); 

(Initialize the printing unit} 

InitPrinting; 

(Allocate the application object) 

NewCgDotApplication); 

FailNILCgDotApplication); 

(Initialize it) 

gDotApplication. IDotApplication; 

Run it) 

gDotApplication.Run; 

END. 


—  ————————  ÁHWr——— 
/* This is the Dots resource file in MPW Rez format. x/ 


"ifdef Debugging 

include MacAppRF i les"Debug.rsrc"; 
Sendif 

include MacAppRF i les"MacApp .rsrc"; 
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include MacAppRF iles"Printing.rsrc"; 
include "Dots" 'CODE'; 

type 'dots' es 'STR '; 

resource ‘dots’ (6) ( "Dots gone V1.0" ); 


data 'ICNS' (129) ( 
$"0000 0000 0000 0000 0000 0000 0000 2000" 
$"0000 0000 0000 0000 0000 0000 0000 0000" 
$"0000 0000 O7FF FFFØ 0400 0010 0400 0010" 
$"0400 0010 0471 C710 0471 C718 0471 C710" 
$"0420 0010 0420 0010 0420 0010 0471 C710" 
$"Ø47F C710 0471 C710 0400 0210 0400 0210" 
$"0400 0218 0471 C710 0471 FF10 0471 C710" 
$"0400 0010 0400 0010 0400 0010 O7FF FFF" 
$'0000 0000 0000 0000 0000 0000 0000 0000" 
$"0000 0000 0000 0000 0000 0000 0000 0000" 
$"0000 0008 OTFF FFFO O7FF FFFO O7FF FFFO" 
$"O7FF FFFO O7FF FFFO O7FF FFFO O7FF FFFO” 
$"O7FF FFFØ O7FF FFFO O7FF FFFO O7FF FFFO" 
$"O7FF FFF O7FF FFFO O7FF FFFO OTFF FFFO" 
$"O7FF FFFO O7FF FFFØ O7FF FFFO O7FF FFFO" 
$"O7FF FFFØ O7FF FFFO O7FF FFFO O7FF FFFO" ); 


data 'ICN8' (128) ( 
$'0000 0000 FFFF FFOO 8000 0100 8000 0100" 
$"8E38 E100 8E38 E100 8E38 E100 8010 0100" 
$'8010 0100 8010 0100 8E38 E100 8FF8 E100" 
$"8E38 E100 8000 0100 8000 3FO0 8000 4080" 
$"8E38 8040 8FF9 3020 8E39 C810 840E 7F8F" 
$'8402 3007 8401 0007 8E38 8007 8E38 6007" 
$"8E38 3FE7 8000 O11F 8000 0107 FFFF FFOO" 
$'0000 0000 0000 0000 0000 0000 0000 0000" 
$'0000 0000 FFFF FFOO FFFF FFOO FFFF FFOO" 
$"FFFF FFØØ FFFF FFØØ FFFF FFØØ FFFF FF00" 
$"FFFF FFØØ FFFF FFØØ FFFF FFOO FFFF FF00" 
$"FFFF FFØO FFFF FFOO FFFF FFOO FFFF FF80" 
$"FFFF FFCO FFFF FFEO FFFF FFFO FFFF FFFF" 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF" 
$"FFFF FFFF FFFF FF1F FFFF FFO7 FFFF FFOO" 
$"0020 0000 0000 0000 0000 0000 0000 0000" Y; 


resource 'FREF' (1280 ( 'APPL', 8, "" ); 
resource 'FREF' (129) ( 'dots', 1, "" ); 
resource 'BNDL' C128) ( 

unes (Ø, 128; — 1, 129); 


'FREF'; (0, 128: 1, 129) 
) 2; 


/* This describes the initial position of a window. 


MacApp automatically replaces the funny title with 


the name of the current document. */ 


resource 'WIND' (128, purgeable) ( 
(58, 18, 304, 222), 
zoomDocProc, invisible, goaway, 8x0, 
"«0»" ); 
/* This is the alert that MacApp displayes in response 
to the About menu item */ 


resource 'DITL' (201, purgeable) ( 
( (136, 182, 150, 262), 
button (enabled, " OK"); 


(10, 80, 40, 270), 


statictext (disabled, 
"Dots game."); 


318 


(50, 80, 110, 270), 

statictext (disabled, 

"Written using MacApp by Lerry Rosenstein, " 
"Apple Computer. 10/14/86"); 

(10, 20, 42, 52), 

icon (disabled, 1) 


) 


resource 'ALRT' (201, purgeable) ( 
(90, 100, 250, 412), 
201, 
( OK, visible, silent; 
OK, visible, silent; 
OK, visible, silent; 
OK, visible, silent ) ); 


/* Here are the menus used by the application. The 
cmnu resource type is like MENU but contains a 
command number for on each item. The PostRez 
MPW tool converts each cmnu resource into a 
MENU resource and creates a sorted table of 
command numbers */ 


resource ‘cmnu' (1) ( 
: textMenuProc, Ox7FFFFFFD, enabled, 
pple, 
C About Dots.", noicon, nokey, nomark, plain, 1; 
"-", noicon, nokey, nomerk, plain, nocommand 


a 


resource 'cmnu' (2) ( 
- textMenuProc, Ox7FFFEEFB, enabled, 
"File" 
("New", noicon, "N", nomark, plain, 10; 
"Open.", noicon, "0", nomark, plain, 29; 
"=" noicon, nokey, nomark, plain, nocommand; 
"Close", noicon, nokey, nomark, plain, 31; 
"Save, noicon, "S", nomark, plain, 30; 
“Save As..", noicon, nokey, nomark, plain, 32; 
"Seve a Copy In.", noicon, nokey, nomark, 
plein, 33; 
"Revert", noicon, nokey, nomark, plain, 34; 
"-", noicon, nokey, nomark, plain, nocommand; 
"Page Setup.", noicon, nokey, nomark, 
plein, 176; 
"Print One", noicon, nokey, nomark, plain, 177; 
"Print.", noicon, nokey, nomerk, plain, 178; 
"=" noicon, nokey, nomark, plain, nocommand; 
"Quit", noicon, "Q", nomark, plain, 36 ) ); 


resource 'cmnu' (3) ( 
3, textMenuProc, Ox7FFFFEBD, enabled, 
"Edit", 

("Undo", noicon, "Z", nomark, plain, 101; 
"=", noicon, nokey, nomark, plain, nocommand; 
"Cut", noicon, "X", nomark, plain, 103; 
"Copy", noicon, "C", nomark, plein, 104; 
"Peste", noicon, "V", nomark, plain, 105; 
"Clear", noicon, noKey, nomark, plain, 106; 
"-", noicon, nokey, nomark, plain, nocommand; 
"Show Clipboard", noicon, nokey, nomark, 

plain, 35 ‘) ); 


/* The buzzwords menu contains strings describing 
commands that are not executed from the menu */ 


resource 'cmnu' (128) ( 
128, textMenuProc, allenabled, enabled, 
"Buzzwords", 
("Last Move", noicon, nokey, nomark, 
plain, 2001 )-5 


/* This resource describes what menus should be 


loaded and displayed when the application starts up */ 
resource 'MBAR' (128) { (1; 2; 3) ); 
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UNIT UDots; 
(* Main part of a MacApp program that plays a simple 
game. Written by Larry Rosenstein, Apple Computer 


UUCP : (nsc, sun}! apple! sr 
CSNET Isr@App le. CSNET 
AppleL ink: Rosensteinl  *) 
INTERFACE 
USES 


( These statements read the interface files for the 
Macintosh ROM routines and for MacApp. The $LOAD is 
used to store the largest interface files in binary 

format for speed. 

($LOAD MacIntf .LOAD) 

MenTypes, QuickDrew, OSIntf, ToolIntf, PackIntf, 
($LOAD UMacApp.LOAD) 

U0bject, UList, UMacApp, 
($LOAD) 


UPr inting; 
CONST 


( size of dot grid; should be even so that there will be 
en odd number of boxes and no tie games 
kDotsPerRow = 6; 

( constants representing the state of a box ) 


kBoxFree = Ø; 
kBoxPlayer 1 = 4; 
kBoxPlayer2 = 5; 


( Number of sides completed; 5 = completed by player2 ) 
BoxState = kBoxFree..kBoxPlayer2; 
( Used to specify the direction of a line. ) 
LineDir = ChLine, vLine); 
( Arrays used to store the state of the game. ) 
LineArray = ARRAY [LineDir, 
l..kDotsPerRow, 1..kDotsPerRow] OF BOOLEAN; 
BoxArray = ARRAYI 1. .kDotsPerRow, 
1..kDotsPerRow] OF BoxState; 
ScoreArray = ARRAYI[BOOLEAN] OF INTEGER; 


( KXKKKKAKKKKKKKKKKKKKK ) 


( This is the application object bre It is responsible for: 


creating new documents 
TDotApplication = OBJECTCTApplication) 
PROCEDURE TDotApplication. IDotApplication; 


Every object type has an initialization method such as this. 


FUNCTION  TDotApplication.DoMakeDocument( 
itsCmdNumber: CmdNumber): TDocument; OVERRIDE; 
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( KXXKKEKKKKKAKEKKKKKE ) 


( This is the document object type. It is responsible for: 
creating new views and windows 
reading and writing documents 
manipulating the state of the game } 


TDotDocument = OBJECT(TDocument) 


fDotView: TDotView; ( The view of the game ) 
fScoreView: ^ TScoreView; ( The view of the score ) 
fPlagerlTurn: BOOLEAN; ( TRUE if player 1's turn ) 
fLines: LineArray; ( State of evey line ) 
fBoxes: BoxArray; ( And box ) 


PROCEDURE TDotDocunent . IDotDocument ; 


( Methods to create views and windows. ) 
PROCEDURE TDotDocument .DoMakeV iewsCforPr int ing: 
BOOLEAN); OVERRIDE; 
PROCEDURE TDotDocument .DoMakeWindows; OVERRIDE; 
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( Methods to read/write document and create new documents. 
DoInitialState is called for new documents; 
DoRead for opening a document ; 
DoNeedDiskSpace is called when MacApp saves a 
document. MacApp will check to see that there is 
enough disk space available.) 


PROCEDURE TDotDocument .DoInitialState; OVERRIDE; 
PROCEDURE TDotDocument .DoNeedDiskSpace(VAR 
dataForkBytes, rsrcForkBytes: LONGINT); OVERRIDE; 
PROCEDURE TDotDocument .DoRead(aRefnum: INTEGER; 
rsrcExists, forPrinting: BOOLEAN); OVERRIDE; 
PROCEDURE TDotDocument .DoWr i teCaRef num: INTEGER; 
makingCopy: BOOLEAN); OVERRIDE; 


( Methods to manipulate the game state. These can be called 
by anyone. 
CalculateScore gives you the current score. 
GetBoxState returns the state of a box. 
GetLineState and SetLineState manipulate the state of 
each line. ) 
PROCEDURE TDotDocument .CalculateScore( 
VAR theScore: ScoreArray); 
FUNCTION TDotDocument .GetBoxState( 
row, col: INTEGER): BoxState; 
FUNCTION TDotDocument .GetL ineState(direction: LineDir; 
row, col: INTEGER): BOOLEAN; 
PROCEDURE TDotDocunent .SetL ineState(direction: LineDir; 
row, col: INTEGER; forPlayer1, newState: BOOLEAN); 


( Private method. ) 
PROCEDURE TDotDocument . ChangeBoxState( 
row, col: INTEGER; 
forPlayer1, addingLine: BOOLEAN); 
END; 


( X Xx Xx x x xoxoxoooooooeeexxo ) 


( This is the main view object type. It is responsible for: 
drawing on the screen 
handling mouse clicks ) 


TDotView = OBJECTCTView) 
fDotDocument: TDotDocument; 


PROCEDURE TDotView. IDotView( 
itsDocument: TDotDocument); 


( Drawing methods ) 
PROCEDURE TDotView.DrawCarea: Rect); OVERRIDE; 
PROCEDURE TDotView.DrawCorner(row, col: INTEGER); 
PROCEDURE TDotView. InvalBox(row, col: INTEGER); 
PROCEDURE TDotView. InvalLine(direction: LineDir; 

row, col: INTEGER); 


( Mouse handling method ) 

FUNCTION TDotView.DoMouseCommand( 
VAR downLocalPoint: Point; VAR info: Event Info; 
VAR hysteresis: Point): TCommand; OVERRIDE; 


( Utility methods that convert between the visual 
representation of the game and the internal data 
Structures. For example, Box2Rect returns the rectangle 
on the screen that corresponds to a particular box. ) 


PROCEDURE TDotView.Box2Rect(row, col: INTEGER; 

VAR r: Rect); 
PROCEDURE TDotView.Dot2Rect(row, col: INTEGER; 

VAR r: Rect); 
PROCEDURE TDotView.DotCenter(row, col: INTEGER; 

VAR center: Point); 
PROCEDURE TDotView.Line2Pt(direction: LineDir; 
row, col: INTEGER; VAR pt: Point); 

PROCEDURE TDotView.Line2Rect(direction: LineDir; 
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row, col: INTEGER; VAR r: Rect); 
FUNCTION  TDotView.Pt2LineCpt: Point; 

VAR direction: LineDir; 

VAR row, col: INTEGER): BOOLEAN; 
END; 


( XXKKKKKKKKKKKKKKKKKK ) 


( This is the score view object type. It is responsible for: 


drawing the score ) 
TScoreView = OBJECTCTView) 


fDotDocument: TDotDocument; 
fPlayeriTurn: BOOLEAN; (which player is currently 
highlighted (not necessarily whose turn it is ) 


PROCEDURE TScoreView.IScoreViewt 
itsDocument: TDotDocument); 


( Drawing methods ) 
PROCEDURE TScoreView.DrawCarea: Rect); OVERRIDE; 
PROCEDURE TScoreView. InvalScore( 


forPlayer 1: BOOLEAN); 
PROCEDURE TScoreView.SetTurnCplayer 1Turn: BOOLEAN); 


( Utility method ) 
PROCEDURE TScoreView.GetPlayerRect( 


forPlayer1: BOOLEAN; VAR r: Rect); 
END; 


( KXKKKKEKKKKKKKKKKEKK } 


( This is the command object type. It is responsible for: 
tracking the mouse 
doing and undoing a move) 

TDotCommand = OBJECTCTCommand) 


fDotDocument: TDotDocument; 


fDotView: TDotView; 
fPlayer 1: BOOLEAN; { who made move } 
( these fields record the line chosen by the user } 
fDirection: LineDir; 
fRow: INTEGER; 
fCol: INTEGER; 


PROCEDURE TDotCommand. IDotCommand( 
itsDotView: TDotView); 


( Mouse tracking methods ) 
PROCEDURE TDotCommand. TrackConstrainCanchorPoint, 
previousPoint: Point; VAR nextPoint: Point); OVERRIDE; 
PROCEDURE TDotCommand. TrackFeedback( 
anchorPoint, nextPoint: Point; 
turnItOn, mouseDidMove: BOOLEAN); OVERRIDE; 
FUNCTION TDotCommand. TrackMouse( 
eTrackPhase: TrackPhase; 
VAR anchorPoint, previousPoint, nextPoint: Point; 
mouseDidMove: BOOLEAN): TCommand; OVERRIDE; 


( Command processing methods } 
PROCEDURE TDotCommand.DoIt; OVERRIDE; 
PROCEDURE TDotCommand.RedoIt; OVERRIDE; 
PROCEDURE TDotCommand.UndoIt; OVERRIDE; 
END; 

IMPLEMENTATION 

($I UDots. inc1.p) 


320 


CONST 
kTypeCreator - 'dots'; ( my doctype end creator ) 
kWINDid - 128; ( rsrc ID of my WIND resource ) 


kLastMoveCommand = 2901; 
( command number for the Move command; in MacApp 
every menu item is assigned an INTEGER command 
number, which makes it easier to deal with commands ) 


kP layer 1 = TRUE; ( indices for gPlayerPats } 
kPlayer2 = FALSE; 

kS tagger Amount = 19; ( amount to offset each window) 
kHalfDotSize = 3; (half the width of a dot ) 
kFullDotSize - 2*kHalfDotSize * 1; 

kHalfLineSize = | ( half width of occupied line ) 
kFullLineSize - 2*kHalfLineSize * 1; 

kLineOffset = (kFullDotSize - kFullLineSize) DIV 2; 
kDotSpacing z 4*kFullDotSize; ( spacing 
kHalfSpacing - kDotSpacing DIV 2; 

kScoreSpacing = 3*kDotSpacing; 

kScoreInset - 6; 

VAR 


gStaggerCount: INTEGER; { used to stagger windows ) 
gPlayerPats: ARRAY[BOOLEAN] OF Pattern; 

{ the patterns representing the two players ) 
($8 Dots) ( everything in 1 segment ) 


( Here are all the method implementations. I have ordered 
these to meke it easier to read though the code. ) 


( The first thing that happens in the main program is to 
initialize the Toolbox and create & initialize the application 
object. This method just sets up the global variables above.) 


PROCEDURE TDotApplication.IDotApplication; 
BEGIN 
( Specify the main file type of my documents ) 
IApplicationCkTypeCreator?); 
gStaggerCount := Ø; 
gPlayerPats(kPlayer 1] := 1tGray; 
gPlayerPats(kPlayer2] := dkGray; 
END; 


( Next, the application is told to create a document object, 
either one that will be blank or one that will be read from 
disk. In this program I have only one kind of document, so I 
ignore the parameter. MacApp does support multiple document 
kinds in the same application, however. ) 


FUNCTION TDotApplication.DoMakeDocument( 
itsCmdNumber: CmdNumber): TDocument; OVERRIDE; 
VAR dotDoc:  TDotDocument; 
BEGIN 
( This is how you create an object. ) 
NewCdotDoc?; : 
( This signals a failure if the object is NIL; i.e., if we ran 
out of memory. MacApp will catch the failure and display an 
appropriate error message automatically. ) 
FailNilCdotDoc); 
dotDoc. IDotDocument; 
DoMakeDocument := dotDoc; 
END; 


( This initializes the document object. I have this method 
only for consistency with other object types. I could have 
called IDocument directly in the method above. The 
parameters to IDocument specify the document type and creator, 
whether the document uses the data and/or resource fork of the 
file, and whether to leave the data and/or resource fork(s) 
open Ctoimplement disk-based documents). } 


PROCEDURE TDotDocument . IDotDocument ; 
BEGIN 
IDocument(kTypeCreator, kTypeCreator, 
kUsesDataFork, NOT kUsesRsrcFork, 
NOT kDataO0pen, NOT kRsrcOpen); 
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END; 


( Once we have an initialized document MacApp either calls 
DoInitialState to set it up as a blank document, or DoRead to 
read it from the disk. These methods are also called in 
response to a Revert command. ) 


PROCEDURE TDotDocument.DoInitialState; OVERRIDE; 


VAR direction: LineDir; 
row: INTEGER; 
col: INTEGER; 


BEGIN 
( Erase all the lines in the grid , and clear the boxes) 
FOR row := 1 TO kDotsPerRow DO 
FOR col := 1 TO kDotsPerRow DO BEGIN 
FOR direction := hLine TO vLine DO 
flines{direction, row, col] := FALSE; 
fBoxes[row, col] := kBoxFree; 


( Have player 1 go first } 
fPlayeriTurn := TRUE; 


é 


( When this method is called, MacApp has already opened the 
file for us. forPrinting is TRUE if the user chose Print from 
the Finder; in some cases you can optimize your reading if you 


know that you are only printing. } 


PROCEDURE TDotDocument .DoRead(aRefnum: INTEGER; 
rsrcExists, forPrinting: BOOLEAN); OVERRIDE; 

VAR count: LONGINT; 

BEGIN 


x: INTEGER; 
( This reads the print state saved in the file ) 
INHERITED DoReadCeRefnum, rsrcExists, forPrinting); 
( Read whose turn it is. ) 
count := 2; 
Perea count, @x)); 
Fxs 
THEN fPlayeriTurn := TRUE 
ELSE fPlayeriTurn := FALSE; 
( Read the line states ) 
count := SIZEOFCLineArray); 
FailOSErrCFSReadCeRefnum, count, @fLines)); 
( and box states. ) 
count := SIZEOF(BoxArray); 
FeilOSErr(FSReadCeRefnum, count, @fBoxes)): 
END; 


( Now we have the document read in, so we meke views that 
display the document on the screen. Since we don't print the 
Score, we don't need a score view if we ere just printing. ) 


PROCEDURE TDotDocument .DoMekeV iews( 
forPrinting: BOOLEAN); OVERRIDE; 
VAR dotView: TDotView; 
scoreView: 
BEGIN 
NewCdotView); 
FailNILCdotView); 


dotView.IDotViewCSELF); 
fDotView := dotView; 


TScoreV iew; 


IF forPrinting 

THEN fScoreView := NIL 

ELSE BEGIN 
NewCscoreView); 
Fai INILCscoreView); 
scoreView. IScoreView(SELF); 
fScoreView := scoreView; 

END; 

END; 


( Here are the methods for initializing the views. ) 
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PROCEDURE TDotView. IDotView( 
itsDocument: TDotDocument); 
VAR Side: INTEGER; 
extent: Rect; 
aHandler: TStdPrintHandler; 
BEGIN 
Side := (kDotsPerRowt 1)*kDotSpacing; 
SetRectCextent, Ø, Ø, side, side); 
fDotDocument :- itsDocument; 


( sizeFixed tells MacApp that the view changes size only when 
you set it; you can also have MacApp automatically make the 
view an integra! number of pages, or exactly 1 page. ) 


IView(NIL, itsDocument, extent, sizeFixed, sizeFixed, TRUE, 
hl0ff); 


( creating a TStdPrintHandler is all you need to do to make a 
view printable. } 

NewCaHandler ); 

FailNILCeHandler); 

eHandler.IStdPrintHendlerCSELF, FALSE); 
END; 


PROCEDURE TScoreView. IScoreView( 
itsDocument: TDotDocument); 
BEGIN 


fDotDocument := itsDocument; 
fPlayer Turn := itsDocument . f Player 1Turn; 
IView(NIL, itsDocument, gZeroRect, sizeFrame, 
sizeFrame, TRUE, hl0ff); 
END; 


( If we aren't printing, then MacApp calls this to create one 
or more window to display the views. ) 


PROCEDURE TDotDocument .DoMakeWindows; OVERRIDE; 
VAR aWindow: TWindow; 
BEGIN 


( NewPaletteWindow is a utility provided by MacApp that 
creates a window containing 2 views. One is a main view that 
cen scroll end the other is a palette/status view that does 
not scroll. There is also a routine called NewSimpleWindow 
that creates a window with only 1 scrollable view. ) 


eWindow := NewPaletteWindowCkWINDid, 
NOT kDialogWindow, kWantHScrollBer, 

kWantVScrollBer, fDotView, fScoreView, kDotSpacing* 
kHalfSpacing, kTopPalette); 
( This is enother utility that staggers windows on screen. ) 
SimpleStaggerCaWindow, kStaggerAmount, 

kStaggerAmount, gStaggerCount); 

END; 


( The first event the we will receive is one to update the 
windows. This results in calling the Draw methods of the 2 
views. } 

( This method draws the grid. If we wanted to optimize it, we 
could examine the area parameter and determine the minimum 
number of rows and columns that need to be drawn. ) 


PROCEDURE TDotView.DrewCarea: Rect); OVERRIDE; 
VAR row, col: INTEGER; 
BEGIN 


FOR row := 1 TO kDotsPerRow DO 
FOR col := 1 TO kDotsPerRow DO 
DrawCorner(row, col); 
END; 
( This does all the work. ) 


PROCEDURE TDotView.DrawCorner(row, col: INTEGER); 
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VAR r: Rect; 
boxState: BoxState; 
lineState: BOOLEAN; 
BEGIN 
IF Crow < kDotsPerRow) AND 
(col « kDotsPerRow) 
THEN BEGIN 


PenNormal ; 
Box2Rect(row, col, r2; 


( First drew the box if it needs to be shaded in. 
boxState := fDotDocument.GetBoxState(row, col); 


IF boxState = kBoxP layer 1 
THEN BEGIN 
FillRect(r, gPlayerPats[kP layer 11); 
FreneRect(r); 
END 
ELSE IF boxState = kBoxPlayer2 
THEN BEGIN 
FillRect(r, gPlayerPats[kPlayer21); 
FremeRect(r); 
END; 
END; 
Dot2Rect(row, col, r2; 
PenNormal; 
PenSize(kFullLineSize, kFullLineSize); 
( Then draw the line down from the dot Cif any) ) 
IF Crow « kDotsPerRow) AND 


fDotDocument .GetLineState(vLine, row, col) 


THEN BEGIN 


MoveToCr.left*kLineOffset, r.toptkLineOffset); 


Line(®, kDotSpacing); 
END; 
( And the line to its right Cif any) ) 
IF (col < kDotsPerRow) AND 


fDotDocument .GetLineStateChLine, row, col) 


THEN BEGIN 


MoveTo(r. lefttkLineOffset, r.toptkLineOffset); 


LineCkDotSpacing, 9); 


END; 

( Finally drew the dot itself ) 
Fill0val(r, black); 

END; 


( Utilities used in drawing the grid.) 


( This gets the state of a box. ) 
FUNCTION TDotDocument .GetBoxState 


BEGIN 
GetBoxState := fBoxes[row, col]; 


row, col: INTEGER): BoxState; 


e. 
4 


( This gets the state of a line. ) 


FUNCTION TDotDocument .GetL ineSteteCdirection: LineDir; 
row, col: INTEGER): BOOLEAN; 


BEGIN 
GetLineState := fLines(direction, row, col]; 
END; 


( This gets the rectangle defining a box. ) 
PROCEDURE TDotView.Box2Rect(row, col: INTEGER; 


VAR r: Rect); 


VAR center: Point; 
BEGIN 
DotCenter(row, col, center); 


SetRect(r, 0, 0, kDotSpacing*1, kDotSpacing+ 1); 


OffsetRect(r, center.h, center.v); 


InsetRect(r, kHalfLineSizet4, kHalfLineSize+4); 


END; 


( This returns the rectangle that defines a particular dot. 


TDotView.Dot2Rect(row, col: INTEGER; 


VAR r: Rect); 


VAR center: Point; 
BEGIN 
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DotCenter(row, col, center); 
SetRect(r, -kHalfDotSize, -kHalfDotSize, 
kHalfDotSize*1, kHalfDotSizet1); 
OffsetRect(r, center.h, center.v); 
END; 


(Here is the Draw method for the score view. ) 
PROCEDURE TScoreView DrawCarea: Rect); OVERRIDE; 


VAR score: ScoreArray; 
player: BOOLEAN; 
ri Rect; 
S: Str255; 
offset: INTEGER; 
BEGIN 
TextFont(monaco); 
TextFaceCL 12; 
TextSize(9); 
PenNormal; 


PenSizeCkScoreInset, kScoreInset); 

fDotDocument .CalculateScore(score); 

FOR player := kPlayer! DOWNTO kPlager2 DO BEGIN 
NumToString(score (player J, S); 

( center score in the player's rectangle ) 
GetPlayerRect(player, r); 
offset := (r.right - r.left - StringWidth(s)) DIV 2; 
MoveTo(r. left + offset, r.bottom-3); 
DrawString(s); 
InsetRect(r, -kScoreInset, -kScoreInset?; 
PenPatCgP layerPats [player 1); 
FrameRect(r); 
END; 


GetPlayerRect(fPlayer Turn, r); 
InvertRect(r); 
END; 


( This computes the current score. We could have stored the 
score in the document object and updated it on the fly, but 
this was easier.) 


PROCEDURE TDotDocument .CalculateScore( 
VAR theScore: ScoreArray); 
VAR row: INTEGER; 
col: INTEGER; 
BEGIN 


theScore(kPlayer1] := Ø; 
theScore[kPlager2] := Ø; 
FOR row := 1 TO kDotsPerRow-1 DO 
FOR col := 1 TO kDotsPerRow-1 DO 
CASE fBoxes[row, coll OF 
kBoxP layer 1: 
theScore[kPlager1] := 
theScore[kPlager1] + 1; 
kBoxP layer2: 
theScore[kPlayer2] := 
theScore[kPlager2] + 1; 


END; 
END; 


( This gets the rectangle in which to drew player's score. ) 
PROCEDURE TScoreView.GetPlagerRect( 

forPlayer1: BOOLEAN; VAR r: Rect); 
BEGIN 


SetRect(r, kDotSpacing, kHalfSpacing, 
2*kDotSpacing, kDotSpacing); 
IF NOT forPlayer 1 


THEN OffsetRect(r, kScoreSpacing, 0); 
END; 


( The next part of the program deals with handling a mouse 
click in the grid. ) 


( When the user clicks the mouse MacApp calls the 


DoMouseCommand method. This returns an appropriate 
command object, which then tracks the mouse. ) 
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FUNCTION TDotView.DoMouseCommand( 
VAR downLocalPoint: Point; 
VAR info: EventInfo; 
VAR hysteresis: Point): TCommand; OVERRIDE; 
VAR dotCmd: TDotCommand; 
BEGIN 
{ In this case, we have only one kind of mouse command. } 
New(CdotCmd); 
FailNILCdotCmd); 
dotCmd. IDotCommandCSELF 5; 
DoMouseCommand := dotCmd; 
END; 


{ This initializes the command object. } 
PROCEDURE TDotCommand. IDotCommand( 

itsDotView: TDotView); 
BEGIN 


TCommand(kLastMoveCommand); 

fConstrainsMouse := TRUE; 

fDotView := itsDotView; 

fDotDocument := itsDotView.fDotDocument; 

fPlayer1 := fDotDocument .fP'ayer 1Turn; 

fDirection := hLine; 

fRow := Ø; 

fCol := Ø; 
END; 


( Once MacApp gets the command object, it runs a loop as 
long as the user holds the button down. In the loop, MacApp 
continually calls the following tracking methods. } 


( This is used to give the command object a chance to modify 
the actual mouse point before it is handled. ) 
PROCEDURE TDotCommand. TrackConstrain( 

anchorPoint, previousPoint: Point; 

VAR nextPoint: Point); OVERRIDE; 


VAR direction: LineDir; 
row: INTEGER; 
col: INTEGER; 


BEGIN 
( In this case, if the mouse is over a line, and the line is 
unoccupied, we change the mouse point into a canonical point 
for that line. This means that if the user points to the 
same line, the TrackMouse method (below) will receive the 
same coordinate even if the mouse moves slightly. This 
prevents the highlighting from flickering. } 
IF fDotView.Pt2LineCnextPoint, direction, row, col) 
THEN BEGIN 
IF fDotDocument .GetLineState(direction, row, col) 
THEN BEGIN 
( the line is already occupied ) 
row : 


li 
Q RQ 
we 


fDotView.Line2Pt(direction, row, col, nextPoint); 
END; 
END; 


( This method provides highlighting while tracking. The 
value of nextPoint is that returned by TrackConstrain. } 
PROCEDURE TDotCommand. TrackFeedback( 

anchorPoint, nextPoint: Point; 

turnItOn, mouseDidMove: BOOLEAN); OVERRIDE; 


VAR direction: LineDir; 
row: INTEGER; 
col: INTEGER; 
r: Rect; 


BEGIN 

( Don't do anything if the mouse doesn't move, to prevent 
flicker. Because of the constraining above, mouseDidMove 
will be FALSE until the user moves completely off the previous 


line, even if the mouse actually does move. ) 
IF mouseDidMove 
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THEN BEGIN 
( if the mouse is over a line, invert it; TrackConstrain 
already made sure that the line is unoccupied ) 
IF fDotView.Pt2LineCnextPoint, direction, row, col) 
THEN BEGIN 
fDotView.Line2Rect(direction, row, col, r); 
InvertRect(r); 
END; 


END; 
END; 


( TrackMouse actually receives the current position of the 
mouse, possibly modified by TrackConstrain. } 


FUNCTION TDotCommand. TrackMouse( 
aTrackPhase: TrackPhase; 
VAR anchorPoint, previousPoint, nextPoint: Point; 
mouseDidMove: BOOLEAN): TCommand; OVERRIDE; 


VAR direction: LineDir; 
row: INTEGER; 
col: INTEGER; 


BEGIN 
( The default is to return the same command, to continue 
tracking. ) 

TreckMouse := SELF; 
( We don't care what happens until the user releases the 
button. ) 

IF aTrackPhase = trackRelease 

THEN BEGIN 

( Make sure that the mouse is over a line, and record 

the user's choice if so ) 

IF fDotView.Pt2LineCpreviousPoint, 
direction, row, col) 


THEN BEGIN 
fDirection := direction; 
fRow := row; 
fCol := col; 

END 

ELSE 


( Tell MacApp that nothing really happened ) 
TrackMouse := gNoChanges; 
END; 
END; 


( Here are the utilities used in the mouse tracking.) 


( This returns the center of a given dot. ) 
PROCEDURE TDotView.DotCenter(row, col: INTEGER; 

VAR center: Point); 
BEGIN 


SetPt(center, kDotSpacing*col, kDotSpacing*row); 


8 


( This converts coordinates of a line to a point on grid.) 
PROCEDURE TDotView.Line2PtCdirection: LineDir; 

row, col: INTEGER; VAR pt: Point); 
BEGIN 


( Set pt to center of given dot. ) 
DotCenter(row, col, pt); 

( Offset it to be on the requested line. ) 
IF direction = hLine 
THEN pt.h := pt.h + kHalfDotSize + 1 
ELSE pt.v := pt.v + kHalfDotSize + 1; 

END; 


( This converts the same coordinates to a rectangle. This is 
used for highlighting while tracking and for invalidating when 


the line is chosen. } 


PROCEDURE TDotView.Line2Rect(direction: LineDir; 
row, col: INTEGER; VAR r: Rect); 
VAR center: 


BEGIN 
DotCenter(row, col, center); 


Point; 
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IF direction = hLine 
THEN SetRect(r, 8, -kHalfDotSize, 
kDotSpacingti, kHalfDotSize*1) 
ELSE SetRect(r, -kHalfDotSize, ð, 
kHalfDotSize+1, kDotSpacing* 12; 


OffsetRect(r, center.h, center v); 
END; 


( This converts a point in grid to the coordinates of a line. 


It returns FALSE if the point is not on a line. ) 
FUNCTION TDotView.Pt2Line(pt: Point; 

VAR direction: LineDir; 

VAR row, col: INTEGER): BOOLEAN; 


VAR ok: BOOLEAN; 
modH: ^ INTEGER; 
modV: INTEGER; 

BEGIN 


ok := FALSE; ( assume the worst ) 
( Offset pt by slop allowed before line ) 
pt.h := pt.h + kFullDotSize; 
pt.v := pt.v + kFullDotSize; 
( Determine values of row and col. ) 
row := pt.v DIV kDotSpacing; 
col := pt.h DIV kDotSpacing; 
ok := Crow >= 1) AND Crow <= kDotsPerRow) AND 
(col >= 1) AND (col <= kDotsPerRow); 
IF ok 
THEN BEGIN ( so far so good ) 
( Consider taking pt.v MOD kDotSpacing. In order to be 
on a horizontal line, this must be in the range 
Ø. .2*kFullDotSize] ) 
modH := pt.h MOD kDotSpacing; 
modV := pt.v MOD kDotSpacing; 
( Pick the closest line to the point. j 
IF modH < modV 
THEN BEGIN 
direction := vLine; 
ok := Crow < kDotsPerRow) AND 
(nodH <= 2*kFullDotSize); 
END 


ELSE BEGIN 
direction := hLine; 
ok := (col « kDotsPerRow) AND 
(modV <= 2*kFullDotSize); 
END; 
END; 


IF NOT ok 
THEN BEGIN 
row : 
col : 


now 
a & 
` 


END; 


Pt2Line := ok; 
END; 


( If the user actually does choose a line. MacApp will call 
the DoIt method of the same command object. If the user 
chooses Undo from the menu, MacApp calls the UndoIt 

method. If the user chooses Undo again, MacApp calls 
RedoIt. ) 


PROCEDURE TDotCommand.DoIt; OVERRIDE; 
BEGIN 
fDotDocument .SetLineStateCfDirection, fRow, fCol, 
fPlayer1, TRUE); 
END; 


PROCEDURE TDotCommand.UndoIt; OVERRIDE; 
BEGIN 
fDotDocument .SetLineStateCfDirection, fRow, fCol, 
fPlayeri, FALSE); 
END; 
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PROCEDURE TDotCommand.RedoIt; OVERRIDE; 
BEGIN 


fDotDocument .SetL ineStateCfDirection, fRow, fCol, 
fPlayer 1, TRUE); 
END; 


( This is the method for changing the state of a line. ) 
PROCEDURE TDotDocument .SetLineState(direction: LineDir; 
row, col: INTEGER; 
forPlayeri, newState: BOOLEAN); 
VAR oldState: BOOLEAN; 
BEGIN 


oldState := GetLineState(direction, row, col); 

IF oldState <> newState 

THEN BEGIN { the state actually changed } 

( modify the document data structures ) 
fLines(direction, row, col] := newState; 

( make sure the line is redrawn ) 
fDotView. InvalLineCdirection, row, col); 

( change state of box to right or under line Cif any) ) 
IF Crow < kDotsPerRow) AND (col < kDotsPerRow) 
THEN ChangeBoxState(row, col, 

forPlayer1, newState); 


( change state of box toleft or above line Cif any)} 
IF direction = hLine 
THEN BEGIN 
IF row) 1 
THEN ChangeBoxState(row-1, col, 
forPlayer1, newState); 


END 
ELSE BEGIN 
IF col > 1 
THEN ChangeBoxStateCrow, col-1, 
forPlayer1, newState); 
END; 
END; 


( let the other player have a turn; and make sure the score 
view shows whose turn it is ) 
fPlayeriTurn := NOT fPlayeriTurn; 
fScoreView.SetTurnCfPlayer iTurn); 


LJ 
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( This changes the state of a box. } 


PROCEDURE TDotDocument .ChangeBoxState( 
row, col: INTEGER; forPlayer1, addingLine: BOOLEAN); 
VAR boxState: BoxState; 
delta: INTEGER; 
BEGIN 
( get the old state } 
boxStete := fBoxes[row, col); 
IF eddingLine 
THEN BEGIN 
IF boxState < kBoxPlayer! 
THEN BEGIN 
( the box is not already completed ) 
boxState := boxState + 1; 
IF boxState = kBoxP layer 1 
THEN BEGIN 
( if this was player 2's turn, record that fact } 
IF NOT forPlayer 1 
THEN boxState := kBoxPlayer2; 
{ the box was just completed, so change the box ... } 
fDotView. InvalBoxCrow, col); 
... and score } 
fScoreView. InvalScore(forPlayer 1); 
END; 
END; 
END 
ELSE BEGIN ( removing a line} 
IF boxState >= kBoxP layer 1 
THEN BEGIN 
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( used to be completed, make sure box is redrawn ... ) END; 


fDotView.InvalBoxCrow, col); END; 
( ... and score is updated ) ( Lest but not least, here are the 2 methods needed in order 
fScoreView.InvalScore(CforPlayer 1); to save games on the disk. ) 
END; 
( This computes the disk space required by the document. 
( update the state of the box appropriately ) MacApp will make sure that there is enough disk space 
IF boxState = kBoxPlayer2 available to save a brand new copy of the document, before 


THEN boxState 
ELSE boxState 


deleting the original version. } 


boxState - 1; 


END; PROCEDURE TDotDocument .DoNeedDiskSpace( 
VAR dataForkBytes, 
( finally change the data structure ) rsrcForkBytes: LONGINT); OVERRIDE; 
fBoxes[row, col] := boxState; BEGIN 
END; INHERITED DoNeedD iskSpace( 
dataForkBytes, rsrcForkBytes); 
dataForkBytes := SIZEOFCLineArray) + 
{ These 4 methods make sure that the views are updated } SIZEOF(BoxArray) + 
PROCEDURE TDotView.InvalLineCdirection: LineDir; 2 (for recording whose turn it is); 
row, col: INTEGER); END; 
VAR r: Rect; 
BEGIN 
Line2Rect(direction, row, col, r); ( This actually does the file output. Notice that this 
InvalidRect(r); parallels the structure of the DoRead method above. } 
END; 
PROCEDURE TDotDocument .DoWriteCaRefnum: INTEGER; 
PROCEDURE TDotView.InvalBoxCrow, col: INTEGER); makingCopy: BOOLEAN); OVERRIDE; 
VAR r: Rect; VAR count: LONGINT; 
BEGIN X: INTEGER; 
Box2Rect(row, col, r); BEGIN 
InvalidRect(r); INHERITED DoWriteCaRefnum, makingCopy); 
8 
IF fPlayer iTurn 
PROCEDURE TScoreView. InvalScore( THEN x := 1 
forPlayer 1: BOOLEAN); ELSE x := 2; 
VAR r: Rect; count := 2; 
BEGIN Fail0SErr(FSWriteCaRefnum, count, @x)); 
GetPlayerRect(forPlayer1, r); count := SIZEOF(LineArray); 
InvalidRect(r); Fail0SErr(FSWriteCaRefnum, count, @fLines)); 
END; count := SIZEOFCBoxArray); 
Fail0SErr(FSWriteCaRefnum, count, @fBoxes)); 
PROCEDURE TScoreView.SetTurn(player 1Turn: BOOLEAN); END; 
VAR r: Rect; 
BEGIN ( 
( This method actually draws on the screen, since it is easy THE END 


to update the turn indication ) 
Notice that there was no code here for moving/resizing 


IF playeriTurn © fPlayer iTurn windows, printing, scrolling, displaying error messages, 

THEN BEGIN handling DAs, ... 

(This sets up current port to draw in score view.) 
fFrame.Focus; All these features are implemented automatically by MacApp. } 
GetPlayerRect(fPlayer Turn, r); 
Inver tRect(r); - 
GetPlayerRectCplayeriTurn, r); E 
InvertRect(r); od 
fPlayeriTurn := player iTurn; SE 
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Advanced Mac'ing 
Reusable MacApp Classes 


Kurt Schmucker is Technical 
Director for Educational Services at PPI 
in Sandy Hook, CT. He is also author 
of the best selling book Object- 

Oriented Programming for the 
Macintosh. In this article, Kurt 
introduces us to some nifty object 
oriented programming constructs for 
MacApp. 


Designing Reusable Classes 
for 
MacApp Applications 


Introduction 


One of the most important 
benefits of object-oriented 
programming is the ability to easily 
reuse code. This reusability is of a 
completely different nature than the 


reusability of the Mac Toolbox, on one 
hand, and a Pascal unit, on the other. This is because of the 


dynamic binding and inheritance of object-oriented languages, 
of which Object Pascal is one example. In an object-oriented 
language, the messages sent to objects are not resolved until 
run-time and this resolution depends on the class of the object 
that receives the message. This dynamic binding is essential 
to the design and implementation of a framework like 
MacApp. For example, when MacApp wants to draw the 
interior of one of the windows in your application, it sends 
the Draw message to the view object installed in that window 
with some code like this: 


dd 
HEHUdHE 


window.fView.Draw; 


The view that receives this message will be an instance 
of some view class that you have designed, and since you 
overrode its Draw method, the code you wrote will be invoked 
by this message. In this way even though the MacApp 
framework was written independently from your application, it 
can still call your code. 

In addition, this same message (window.fView.Draw) is 
used for all the windows. For each window, the Draw 
message is sent to the appropriate view object which "knows" 
how to draw itself. Thus, the MacApp code for the TWindow 
class is reusable across all MacApp applications since it can 
be used without change in all of them. 

There is also another kind of reusability. You might 
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Fig. 1 The QuadWorld Program 


want to reuse all the functionality of the MacApp TWindow 
class, for example, except that you want one little change: you 
want a window that always asks for a confirmation before 
opening or closing. (Okay, so this is a weird thing to do. I'm 
Just trying to make a point.) In an object-oriented language 
like Object Pascal, this is easy to do. You just design a new 
subclass of TWindow, call it TConfirmingWindow. This new 
class inherits all the functionality of the TWindow class, but 
in addition, you can augment the actions taken when the 
window opens or closes by designing your own methods for 
the Open and Close messages. Designing your own methods 
for the TConfirmingWindow is considerably easier than 
defining your own window or menu definition procedures — 
the closest analog on the Mac. For example, this would be 
the way you would augment the open behavior of the window: 


PROCEDURE TConfirmingWindow.Open; OVERRIDE; 
BEGIN 
IF SELF.ConfirmOpen 
THEN INHERITED Open; 
END; 


This method is invoked when an instance of 
TConfirmingWindow is sent the Open message. This method 
first sends the message ConfirmOpen to this window, 
presumably to ask the user if this window really should appear 
on the Mac screen. If the answer is yes, this method then 
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invokes its inherited Open method: the Open method for the 
TWindow class. 

In this last example, you have reused code by inheriting 
it, overriding to augment the existing behavior of the window. 
The bottom line is that to implement the confirming window 
took you just a few lines of code. 

This article discusses how you can use dynamic binding 
and inheritance to build your own reusable MacApp classes. 
In doing so, we will develop such a class and demonstrate its 
reusability by subclassing it to achieve two new kinds of 
functionality with only the minimum of work. 

Note that the style of reusability possible in an object- 
oriented language is not meant to replace the kinds of software 
packaging found in traditional subroutine libraries like the 
Toolbox or a unit. Rather it is an additional tool in the hands 
of the Mac programmer, a tool that is appropriate for many 
tasks but not everything. 


Rules of Thumb for Reusable Classes 


Using an object-oriented language does not guarantee 
reusable software, just as using structured programming does 
not guarantee readable or maintainable code. Object-oriented 
programming does, however, give you the potential for a level 
of reusability unachievable in languages that do not have 
dynamic binding or inheritance. 

Here are some of the rules of thumb that I use to design 
reusable classes. Like all rules of thumb, they are meant to be 
followed in moderation. 


Rule 1: Whenever you are faced with a choice, design a new 
method. 

Rule2: Methods should be single purpose. 

Rule3: Store as instance variables the data that is needed 
by more than one of your methods, or data that 
may be needed by a subclass. 

Rule 4: In deciding on the superclass for a new class, 
method inheritance is more important than data 
inheritance. 

Rule 5: Write for the library, not just for yourself. 

Rule6: Code defensively. You never know who will call 


your methods and under what circumstances. 


Rule 1 encourages all major and most minor decisions to 
be made in separate methods so that these decisions can be 
overridden in subclasses. This gives the class the maximum 
flexibility as a base for new subclasses. Because this principle 
was followed in MacApp, it was easy to design the 
TConfirmingWindow class. What should happen when a 
window is to be open is a single method in the class and thus 
to change this in the subclass, only one method need be 
overridden. There is one drawback to following this rule: 
proliferation of methods. You can see this in MacApp, which 
consists of only 39 classes but over 560 methods. The 
benefits of this rule, however, outweigh this inconvenience. 

Rule 2 reiterates that methods should be replaceable 
components of building blocks: replaceable in subclasses. If 
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methods are multi-purpose, this is difficult. In the case of the 
TConfirmingWindow class, we were able to override one 
decision — what to do when a window is to be opened — in 
one method, without having to worry about what other things 
this method might do. This made the TConfirmingWindow 
class an excellent base for new classes. A corollary of this 
rule is that methods tend to be short: at most a few dozen 
statements or so. 

Rule 3 encourages you to avoid global variables by 
storing data needed by several methods in instance variables. 
In addition to the data you need, consider also the data that 
might be needed by a subclass: data needed to support different 
resolutions of the decisions you made. (Rule 1) 

Rule 4 helps you decide on the superclass for a class you 
are designing. Examine the behavior you will inherit from the 
superclass rather than the data you will also inherit. 

Rule 5 encourages you to go that extra step or two. 
Don’t do just the bare minimum that will solve the problem 
at hand: design the additional functionality that will make this 
a class worthy of being in a library. 

Rule 6 warns you that since your class may be subclassed 
by many other programmers, its methods may be called in 
circumstances you cannot control. You must therefore code 
extremely defensively. 


QuadWorld Geometric Editor and the 
TListView Class 


The application that will be used to demonstrate this 
design of reusable classes is the QuadWorld application. 
QuadWorld is a simple MacDraw-like geometric editor. It 
allows the user to enter and manipulate various kinds of 
quadrilaterals without regard to the geometric constraints 
associated with special quadrilaterals like rhombi. QuadWorld 
presents two representations (views) of the quadrilaterals to the 
end user: a graphical view and a textual view. It is the textual 
view that will be developed as a reusable MacApp class. 
Figure 1 is a screen dump of QuadWorld in action. For a 
more detailed discussion of the implementation of the 
QuadWorld application, as well as a complete listing of the 
QuadWorld application, see Object-Oriented Programming for 
the Macintosh, Hayden, 1986, by myself. The complete 
Source is also available on the MacTutor Source Code Disk for 
this issue, Number 15, $8.00 from MacTutor.) 

The list view class is a good candidate for some special 
design attention since its functionality — displaying a list of 
text items so that the user can select one with the mouse — is 
needed by many applications. (QuadWorld was designed and 
implemented before the new 128K ROMs with the List 
Manager was released.) Other parts of QuadWorld are not such 
good candidates. After all, how often do you need the code to 
rotate a rhombus? 

This brings up an interesting point. Any class designed 
in Object Pascal can be reused and so, for that matter, can any 
piece of code. What we are talking about here is designing the 
code of a class to be used with the MacApp class library, so 
that it can be reused easily by other programmers who may 


327 


ChangeSelection 


Change the current 
selection properly 


DoHighlightSelection 


Highlight and unhighlight the 
currently selected list item 


PtTolndex 


Convert local 
coordinate point to the 
list item it covers. 


DoMouseCommand 


Resond to mouse clicks 
by selecting list entries 


Draw 
Draw the entire list 


Invalidateltem 


“Fix up” the display of 
the list when one item 
changes 


IListView 


Initialize new instance 
| of TListView 


328 


Debugging print of 
TListView instances 


The TListView Class Structure 


CD COR Ce e RC aD 


efCurrentitem 
;fCu rrentSelection 
;fNumberOfltems 
:fltemHeight 

i fLineAscent 


e aaa Pa a t a a e e ea 


defined in the TListView 
class definition 


Manu utut unnm al LIS nM tn nm a 


inherited from the TView class (along 
with many other instance variables) 


MS a ua n n S a 4 a e Sa a i a n n n n 


SetPen 


Set the list view's 
grafPort pen 
characteristics 


DrawOneltem 


Draw one list entry 


SetUpBox 


Calculate the rectangle 
corresonding to a 
given list item 


SetltemHelghtAndLineAscent 


Set two of the list view parameters 


AboutToDraw 


Performs some 
one-time drawing 
initializations 


Inspect 


CalcMinExtent 


Calculate the size of the view 
upon MacApp's request 


Fig. 2 


O The Complete MacTutor, Vol. 2 


not have access to the source code or don’t want to bother with 
all the fine points of the algorithms involved. These 
programmers will still want to be able to make small 
modifications to the functionality of the class, in the way that 
TConfirmingWindow is a slight modification of the vanilla 
window modelled by TWindow. This can be almost trivial to 
do, if the original class was designed well, by following the 
rules of thumb discussed earlier. 


The TListView Class 


The essential structure of the TListView class is shown 
in Figure 2. This collection of methods follows most (if 
not all) of the rules outlined above. For example, since I had 
to make a choice when setting up the QuickDraw port (font, 
text size, text style, etc.), I coded my preference in a separate 
method (SetPen). If you needed the functionality of this class, 
but wanted one of these characteristics to be different, you 
would only have to subclass TListView and override this one 
method. 

Less obviously, whenever I am about to do something 
with an entire entry in the list (test for coverage by a mouse 
click, highlight, or move the pen into position for drawing), I 
use a method to compute the rectangle surrounding an item. 
Who knows, perhaps someone would want to accomplish this 
aspect of a list view differently. (In fact, the last section of 
this article does exactly this.) 

In the area of data, the fCurrentItem instance variable 
always stores the number of the item currently being processed 
(drawn, enumerated, etc.) in case a subclass needs to use it. 
The fltemHeight variable stores the height of an individual 
item since this data is needed by several methods. 

Of course, like any good idea, you can carry these rules-of- 
thumb of class design too far. Abusing rule 1, for example, 
will result in so many methods that no one can understand 
what is going on and, in addition, performance will degrade. I 
hope that I have successfully straddled the fence between a 
class that can't easily be used as a basis for inheritance and one 
with so many methods as to be incomprehensible. 


When a class is properly designed, note how short and 
simple the methods turn out: 


PROCEDURE TListView.ChangeSelection( 

index: INTEGER); 
BEGIN 
SELF.fFrame.Focus; 
SELF.DoHighlightSelection(SELF.fHLDesired, hlOff); 
SELF.fCurrentSelection : index; 
SELF.DoHighlightSelection(hlOff, SELF.fHLDesired); 
END; 


FUNCTION TListView.DoMouseCommand( 

VAR downLocalPoint: Point; 

VAR info: Eventinfo; 

VAR hysteresis: Point): TCommand; OVERRIDE; 

VAR index: INTEGER; 

BEGIN 

(If this mouse press results in a change of the current 
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selection, let the document deal with it in any way it chooses. 
This is done because the document might control several 
views, or might deal with a changed selection in some other 
application-specific manner. ) 


DoMouseCommand := gNoChanges; 
index := SELF.PtTolndex(downLocalPoint); 
IF (index > 0) THEN 
BEGIN 
IF fCurrentSelection = index 
{ A click on the current selection means to 
deselect it } 
THEN 
TListDocument(SELF.fDocument). 
SetSelection(0) 
ELSE 
TListDocument(SELF.fDocument). 
SetSelection(index); 
END 
END; 


These methods are short and clear enough that it is easy 
to see that they are correct just by reading them. 

Some of the interrelationships between the methods of 
the TListView class are also shown in Figure 2. Basically, 
there are a few basic methods that encode my decisions to 
some issues as to how a list view should behave 
(DrawOneltem, SetUpBox, SetItemHeightAndLineAscent, and 
SetPen). The rest of the methods are written in terms of each 
other and these basic ones, as you can see in both the 
ChangeSelection and DoMouseCommand methods above. 

To get some new functionality in a subclass of a class 
designed in this way, you only need (usually) to override one 
or more of the basic methods — everything else just works. 
On a considerably larger scale, MacApp works exactly the 
same way. Instead of modelling just a list of selectable items, 
MacApp models an entire Macintosh application and you just 
override some classes to add the functionality that 
distinguishes your application from all other ones. 

The full source code for the TListView class is at the end 
of this article. (Since the MacApp classes can currently only 
be accessed from MPW Pascal, all the sample code and all the 
work for this article was done in MPW. While the latest 
version of TML Pascal supports the Object Pascal extensions, 
it does not yet support other Pascal extensions used by 
MacApp.) 


Some TListView Subclass 


In order to demonstrate the flexibility of a properly 
designed class like TListView, let’s use it as the superclass for 
two new classes. These two new classes will both portray 
lists of items in the QuadWorld application, but each will do 
so in a different way. 


TTwoLineListView 


The TTwoLineListView class presents a two-line entry 
for each quadrilateral. The first line is the type of quadrilateral, 
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Figure 3 


just like in TListView. However this does not allow you to 
distinguish between each of the squares or each of the rhombi, 
for example, without interacting with the view by 
highlighting individual quadrilaterals. TTwoLineListView 
corrects this problem. The second line of an entry in a 
TTwoLineListView display the coordinates of the vertices of 
the quadrilateral. Figure 3 shows a screen dump of 
QuadWorld using the TTwoLineListView. 

To accomplish the functionality of the 
TTWoLineListView we had do nothing more than subclass 
TListView and override two of its basic methods, 
DrawOneltem and SetItemHeightAndLineAscent. Even this 
overriding did not require us to re-implement the functionality 
of the basic methods in TListView, but merely augment their 
computations. As was mentioned in Ken Doyle’s article on 
Object Pascal, the keyword INHERITED can be used to access 
a method of an ancestor or superclass. In TTwoLineListView, 
I did so in both of its methods. 

Since the major theme of this article is reusability in 
MacApp, let me document the steps to add 
TTwoLineListView to QuadWorld, in particular, and the 
general steps of adding any new class to an application written 
with MacApp. Adding a new view like the two-line list view 
to an application like QuadWorld consisted of the following 
amount of work: 

(D Design the new class. 

4 For the TTwoLineListView this was about 30 lines of 
MPW Pascal with a stub routine for the construction and 
formatting the line of text representing the vertices. (See step 
4.) 

Q Incorporate this new class into the application. 

4 Modify the make file to include dependencies on the 
new class file. In the case of the QuadWorld make file, this 
was three modifications, each of which were adding another 
dependency to an existing rule. 

4 Modify the USES statement in the application’s major 
unit (UQuadWorld.p, in the case of QuadWorld) and main 
program (MQuadWorld.p) by adding the name of the new unit 
to the existing USES statement. 
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Y Refer to the new class in the major unit of the 
application. In the case of the TTwoLineListView class in 
QuadWorld, this consisted of modifying the data type of one 
temporary variable in method TQuadDocument.DoMakeViews 
from the type TListView to the type TTwoLineListView. 
This causes an object of the TTwoLineListView class to be 
allocated at run-time and to be connected to the other objects 
that comprise the QuadWorld application. 

@ Add whatever features necessary to the application to 
generate any new information needed by the new class. 

V. For QuadWorld, this meant providing methods in the 
TQuadDocument class and in the various quadrilateral classes 
to generate a string representing the vertex coordinates of any 
quadrilateral. 


TMinilconListView 


The TMinilconListView solves the problem of the 
individual who cannot remember which is a rhombus and 
which is a parallelogram since it presents a little icon for each 
type of quadrilateral. This icon is the same for all 
quadrilaterals, for all parallelograms, etc. Figure 4 shows a 
screen dump of QuadWorld using the TTwoLineListView. 

To implement TMinilconListView, I inherited from 
TListView and overrode only the DrawOneltem basic method. 

Adding the necessary features to QuadWorld to generate 
the information needed by the mini-icon view (step 3 above) 
provides an interesting example of how programming with an 
object-oriented language differs from programming with a non- 
object-oriented language. My first version of 
TMinilconListView.DrawOneltem ignored the peripheral issue 
of generating this information, concentrating rather on the 
structural issues of the new class that was being designed. 
This was done by using a stub routine for actually obtaining 
and drawing the icon: 


PROCEDURE TMinilconListView.DrawOneltem 


(item: Str255); OVERRIDE; 
{ Draw the mini-icon } 
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PROCEDURE Drawlcon; 
VAR tempRect: Rect; 


BEGIN 
( The rectangle into which the icon will be drawn } 
tempRect := SELF.SetUpBox(SELF.fCurrentltem); 
tempRect.right := tempRect.left + SELF.fltemHeight; 
{ Fake the icon for now } 
InsetRect(tempRect, 4, 4); 
FrameRect(tempRect); 
END; 


BEGIN 

Drawlcon; 
Move(SELF.fltemHeight, 0); 
INHERITED DrawOneltem(item); 
END; 


To complete the TMinilconListView class required 
fleshing out this stub. There were two extremes for this task: 
a non-flexible, non-object-oriented, closed solution something 
like this: 


( Get the icon by testing the itemString ) 
CASE item OF 
‘a Quadrilateral’: icon := quadlcon; 
‘a Parallelogram": icon := parallelogramlcon; 
‘a Rhombus': icon := rhombusicon; 
'a Rectangle’: icon := rectanglelcon; 
'a Square’: icon := squarelcon; 
OTHERWISE icon := quadlcon 


or a flexible, object-oriented, open solution something like 
this: 


( Get the icon by "asking" the quad what its icon is ) 
icon := (SELF.fCurrentltem).AsQuad.MinilconNumber 


The object-oriented solution tums out to be slightly 
longer, but was so much clearer and more malleable with 
respect to future changes in QuadWorld that there really wasn't 
any Choice as to which was the truly “best” solution. 

To be more precise, the modifications to QuadWorld to 
generate the information needed by the mini-icon view were: 

® “Flesh” out the stub routine as follows: 


PROCEDURE TMinilconListView.DrawOneltem 
(item: Str255); OVERRIDE; 
( Draw the mini-icon ) 
PROCEDURE Drawlcon; 
VAR tempRect: Rect; 
tempHandle: Handle; 
myDocument: TMinilconListDocument; 
BEGIN 
( The rectangle into which the icon will be drawn ) 
tempRect := SELF.SetUpBox(SELF.fCurrentltem); 
tempRect.right := tempRect.left + SELF.fltemHeight; 
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{ Get the icon } 
myDocument := 
TMinilconListDocument(SELF.fDocument); 
tempHandle := 
Geticon(myDocument.ReportlconNumber 
(SELF.fCurrentitem)); 
FailNIL(tempHandle); 


( Draw the Icon ) 
Plotlcon(tempRect, tempHandle); 


BEGIN 

Drawlcon; 
Move(SELF.fltemHeight, 0); 
INHERITED DrawOneltem(item); 
END; 


@ Add the new method ReportIlconNumber to the 
TDocument class displayed by the TMinilconListView. 


V This task is one of the few made more difficult by the 
characteristics of MPW Pascal. Even if you know that the 
instance of the subclass of TDocument that you will be using 
in your application will, at run-time, understand a message 
like ReportIconNumber, you must find some way to inform 
the compiler that everything is OK at compile-time. (More 
robust object-oriented languages like Smalltalk-80® and 
Objective-C® have no such requirement.) The solution to 
this difficulty, in the case of Object Pascal, is to define an 
abstract superclass with a null method for ReporticonNumber. 
This is the class TMiniIconListDocument. 

& Change the inheritance of TQuadDocument so that it is 
a specialization of TMinilconListDocument and then 
implement the ReportIconNumber method as follows: 


FUNCTION TQuadDocument.ReportlconNumber 
(itemNumber: INTEGER): INTEGER; OVERRIDE; 
VAR theQuad: TQuad; 
BEGIN 
theQuad := TQuad(SELF.ListlndexToQuad(itemNumber)); 
IF theQuad = NIL 
THEN ReportlconNumber := cQuadlcon 
ELSE ReporticonNumber := theQuad.MinilconNumber; 
END; 


€& Add the MinilconNumber method to all the 
quadrilateral classes so that each kind of quadrilateral “knows” 
what its particular mini-icon number is. 

& Add the resource ids for the five new icons to the 
UQuadWorld unit. 

(€ Add the icon resources to the compiled Quad World 
application with ResEdit. 


The source code for these two subclasses of TListView is 


also appended to the end of this article. For the QuadWorld 
program itself, see Source Code Disk #15. 
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( List View unit used in the QuadWorld Application ) 
( Copyright 1986, Productivity Products International, Inc. ) 
( Reproduction & distribution rights granted to MacTutor ) 


( This unit implements a list view like that of the Smalltalk 
Listview class, i.e., a vertical list of text items any one of 
which can be selected with the mouse. Like the Smalltalk 
class, this TListView makes some assumptions about the 
protocol of the document it displays. In particular, 
TListView assumes that its fDocument field refers to an 
instance of a subclass of TListDocument (defined here) and 
thus has the following additional document methods Cat a 
minimum): 

TCYour )Document .Se tSe lect ion(newSe lect ionIndex); 


This method is used to communicate to your document that the 
selection has changed, presumably because the user has 
selected a text string in the TListView 

TCYour )Document .ReportListItem: Str255; 


A function which returns the textual version of a given item 
to be displayed by the TListView. Note that your document can 
contain primarily non-textual data - the ListView will display 
a textual representation of that data, a representation that 
you construct in this method. 


To see one example of how this ListView class can be 
used, see the QuadWorld application on source disk 15. ) 


UNIT UListView; 
INTERFACE 


USES 
( This set of units are portions of the Macintosh ROM ) 
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 


( This set of units are portions of MacApp ) 
UObject, UList, UMacApp; 


TYPE 
TListDocument = OBJECTCTDocument) 
( en abstract superclass that contains null methods 
needed for the proper use of a list view ) 
( No additional instance variables ) 
PROCEDURE TListDocument .SetSelectionC 
newSelectionIndex: INTEGER); 
FUNCTION TListDocument .ReportListItemC 
itemNumber: INTEGER): Str255; 
END; (of TListDocument ) 


TListView = OBJECTCTView) 
( Instance variables ) 


fCurrentItem: INTEGER; ( index of the current 
selection, if any, otherwise Ø ) 
fCurrentSelection: ^ INTEGER; ( index of the current 
selection, if any, 
otherwise Ø ) 
fNumberOfItems: INTEGER; ( number of items 
currently in the list ) 
fItemHeight: INTEGER; ( height of each line 
including leading ) 
fLineAscent: INTEGER; ( position of baseline 


relative to top of line ) 


( Initielization ) 
PROCEDURE TListView.IListViewC 
itsPerent: TView; — itsDocument: TListDocument; 
itsExtent: Rect; itsVDeterminer: SizeDeterminer; 
itCanSelect: BOOLEAN); 
($IFC qDebug) 
PROCEDURE TListView.Inspect; OVERRIDE; 
( Debugging print of the listView ) 
($ENDC) 
( Commands and Selections ) 
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PROCEDURE TListView.ChangeSelectionC 
index: INTEGER); 
FUNCTION TListView.DoMouseCommandC 
VAR downLocalPoint: Point; VAR info: EventInfo; 
VAR hysteresis: Point): TCommand; OVERRIDE; 
FUNCTION TListView.PtToIndexC 
testPoint: Point): INTEGER; 
( Convert from a point in local view 
coordinates to the index of the list of itemsat 
this point. This is a method so that it can 
easily be overridden by clients. ) 


( Displaying ) 

PROCEDURE TListView.AboutToDraw; OVERRIDE; 
( Set the font and text style ) 

PROCEDURE TListView.CalcMinExtent¢ 
VAR minExtent: Rect); OVERRIDE; 
( This method must be overridden since a list view 
has a variable vertical extent. ) 

PROCEDURE TListView.DoHighlightSelectionC 
fromHL, toHL: HLState); OVERRIDE; 

PROCEDURE TListView.DrawCarea: Rect); OVERRIDE; 

PROCEDURE TListView.DrawOneItemCitem: Str255); 
{ Draw one item. This is here so that it can 

easilly be overridden by a client. } 

PROCEDURE TListView.InvalidateItemC 
itemNumber: INTEGER); 

PROCEDURE TListView.SetItemHeightAndL ineAscent; 
( Setup the item height end ascent for drawing the 
text; this is a method so that it can be overridden 
easily by clients) 

FUNCTION TListView.SetUpBox( index: INTEGER): Rect; 
{ Calculate the surrounding rectangle for an item } 

PROCEDURE TListView.SetPen; 
( Setup the pen for drawing the text; this is a 
method so that it can be overridden easily by 
clients} 

END; ( TListView ) 


IMPLEMENTATION 


( Private data ) 
CONST 

txMargin = 4; { horizontal space between view edge and 
the left edge of the text } 


( ***** TListDocument (an abstract superclass ) ***#*** ) 


PROCEDURE TListDocument .SetSelection( 
newSelectionIndex: INTEGER); 
BEGIN 
($IFC qDebug) 
ProgramBreakC'Call to TListDocument .SetSelection 
- en abstract superclass'); 
($ENDC) 


END; 


FUNCTION TListDocument .ReportListItemC 
itemNumber: INTEGER): Str255; 
BEGIN 
($IFC qDebug) 
ProgramBreak('Call to TListDocument .ReportList 
- an abstract superclass’); 
($ENDC) 


END; 


( XxXxcoeeeeooeex TListView XXXX**EXXXXXEXXXEXXtxxtxxk ) 


PROCEDURE TListView.IListViewCitsParent: TView; 
itsDocument: TListDocument; ^ itsExtent: Rect; 
itsVDeterminer: SizeDeterminer; 
itCanSelect: BOOLEAN); 

BEGIN 

SELF .IViewCitsParent, itsDocument, itsExtent, sizeFixed, 
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itsVDeterminer, itCanSelect, hlDim); 
SELF .fCurrentItem := Ø; 
SELF .fCurrSelection :- Ø; 
SELF .fNumberOf Items := Ø; 
SELF .fItemHeight := 17; ( Reasonable default ) 
SELF .fLineAscent := 12; ( Reasonable default ) 
SELF . f InformBeforeDraw := TRUE; 
( Before drewing the first time, call the 
AboutToDraw method ) 
END; 


($IFC qDebug) 

PROCEDURE TListView.Inspect; OVERRIDE; 
( Debugging print of the listView ) 

BEGIN 
INHERITED Inspect; 
WriteLnC' The current item is: ', SELF.fCurrentItem); 
WriteLnC' The selected item is: ' , SELF .fCurrentSelection); 
WriteLnC' The number of items is: ' , SELF. f NumberOf Items); 
WriteLnC' The item height is: ', SELF.fItemHeight); 
WriteLnC' The line ascent is: ', SELF.fLineAscent); 


END; 
($ENDC) 


( Set the font and text style just before drawing the view for 
the first time ) 
PROCEDURE TListView.AboutToDraw; 
BEGIN 
SELF .SetPen; 
SELF . Set ItemHe ightAndAscent ; 
SELF . AdjustExtent; 
SELF.fInformBeforeDrew := FALSE; {No longer call 
this method ) 


OVERRIDE; 


END; 


( This method must be overridden so that MacApp can determine 
the view's true extent 
PROCEDURE TListView.CalcMinExtent( 
VAR minExtent: Rect); 
BEGIN 


( How many items ere there? ) 
SELF .fCurrentItem := 1; 
WHILE CTListDocument(SELF .fDocument). 
ReportListItemC SELF.fCurrentItem ) © ' ') 
DO SELF.fCurrentItem := SELF.fCurrentItem + 1; 
SELF .fNumberOfItems :- SELF.fCurrentItem - 1; 
SELF .fCurrentItem := Ø; 
( No item currently being processed ) 


OVERRIDE; 


( Set the amount of room needed for that many items ) 
minExtent := SELF.fExtentRect; 
IF SELF.fSizeDeterminer(v] © sizeFixed 
( Only need to adjust vertical extent ) 
THEN minExtent.botRight.v := 
SELF . fNumberOf I tems*SELF .f ItemHeight; 
END; 


PROCEDURE TListView.ChangeSelection¢ 
index: INTEGER); 
BEGIN 


SELF .f Frame .Focus; 

SELF .DoHighlightSelection(SELF .fHLDesired, hl0ff); 
SELF .fCurrentSelection := index; 

SELF .DoHighlightSelectionChlOff, SELF.fHLDesired); 
END; 


( Dim highlighting of text by gray XORing is not very 
readable, so dim highlight a text string by framing it with a 
gray rectangle. (Standard highlighting when the window 
displaying 

the view is active is still to invert - black XORing.) The 
state transition diagram is: 


1To 
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| OFF | DIM | ON 
OFF | (NA) | Frame | Invert 
DIM | Frame | (NA) | Frame + 
hlFrom | | | Invert 
ON | Invert | Invert + | CNA) 
| | Frame | 


Since this matrix is Calmost) symmetric, we can add together 
the hlFrom and hlTo parameters and take one action for each of 
the three possible sums. 


PROCEDURE TListView.DoHighlightSelection( 
fromHL, toHL: HLState); OVERRIDE; 


VAR r: Rect; 
BEGIN 
IF (SELF.fCurrentSelection > Ø) THEN 
BEGIN 


( Meke r be the rectangle to invert ) 
r :7 SELF .SetUpBoxCSELF .f CurrentSelect ion); 
InsetRect(r, 1, 1); 


( Set the pen pattern and mode properly ) 
PenPat(1tGray); 
PenModeCpatXor); 


IF RectIsVisible(r) THEN 
( only do highlighting if part of the rectangle is 


visible 
BEGIN 
CASE (fromH] + toHL) OF 
hlOffDim: FrameRect(r); 
hl0ffün:  InvertRect(r); 
hiDimOn: IF fromHL = hlDim 
THEN BEGIN 
FremeRect(r); InvertRect(r); 
ELSE BEGIN 
InvertRect(r); FrameRect(r); 
END; 
END ( of CASE ) 
END 
END 


END; 


FUNCTION TListView.DoMouseCommandC 
VAR downLocalPoint: Point; VAR info: Event Info; 
VAR hysteresis: Point): TCommand; OVERRIDE; 
VAR index: INTEGER; 
BEGIN 
( If this mouse press results in a change of the 
current selection, let the document deal with it in any way it 
chooses. This is done because the document might contro] 
Several views, or might deal with a changed selection in some 
other application-specific manner. ) 


DoMouseCommand := gNoChanges; 
index := SELF.PtToIndexCdownLocalPo int); 
IF Cindex >» Ø) THEN 
BEGIN 
IF fCurrentSelection = index 
( A click on current selection means to deselect it ) 
THEN 


TListDocument(SELF .f Document) .SetSelection(0) 
ELSE 
TListDocument(SELF .fDocument). 
SetSelectionCindex2; 
END 
END; 


( Write the textual representation of all the items, properly 
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positioned } 
PROCEDURE TListView.DrewCerea: Rect); OVERRIDE; 
VAR bBox: Rect; — ( the bounding box for a single item ) 
stringToDrew: Str255; 


SELF .fCurrentItem := 1; 
( Get each item in turn from the document and drew it ) 
stringToDrew := TListDocument(SELF .fDocument). 
ReportListItemC SELF .fCurrentItem ); 
WHILE (stringToDrew o ' ') DO 
BEGIN 


( Calculate the rectangle to fill ) 
bBox := SELF.SetUpBoxC SELF .fCurrentItem ); 


IF RectIsVisibleCbBox) THEN 
( only write text that will be seen ) 
BEGIN 


MoveTo(CbBox. left + txMargin, 
bBox.top + SELF .fLineAscent?; 
SELF .DrewOneItemCstringToDrew); 


a 


SELF .fCurrentItem:= SELF .fCurrentItem + 1; 
stringToDrew := TListDocument(SELF .fDocument). 
ReportListItemC SELF .fCurrentI tem); 
END; 
SELF .fNumberOfItems := SELF .fCurrentItem - 1; 
SELF .fCurrentItem := Ø; 
m ( No item currently being processed ) 
ND; 


PROCEDURE TListView.DrewOneItemCitem: Str255); 
BEGIN 


DrewStringCitem); 
END; 


( In theory, this method invalidates the area occupied by the 
item, that is, the listDocument will send this message to the 
view when any single item needs to be redrewn and will pass 
the number of this item as the message argument. In reality, 
this method invalidates the entire panel so as not to leave 
"holes" in the textual representation of the document. The 
argument is never used. 


PROCEDURE TListView. Invalidate! tem( 
itemNumber: INTEGER); 
BEGIN 


SELF .AdjustExtent; 
( In case the size of the view has changed ) 
SELF . InvalidRectCSELF .fExtentRect); 
( AdjustExtent will cause & focus ) 
END; 


( Decide what item is indicated by this point; return @ iff 
this point indicates no item ) 
FUNCTION TListView.PtToIndex( 
testPoint: Point): INTEGER; 
VAR i: INTEGER; — ( FOR Loop Index ) 
BEGIN 
PtToIndex := @; ( Assume the item is NOT found ) 
FOR i := 1 TO SELF.fNumberOf Items DO 
IF PtInRectCtestPoint, SELF .SetUpBoxCi2) 
THEN BEGIN 
PtToIndex := i; 
LEAVE ( Don't check the rest ) 
END 
END; 
( Set the line spacing characteristics. This is a separate 
method so that clients can easily override it without also 
having to worry about setting the font. It assumes that SetPet 
has been called and that the view has been focused. } 


PROCEDURE TListView.SetItemHeightAndL ineAscent; 
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VAR fInfo: FontInfo; 
BEGiN 
GetFontInfoCf Info); 
WITH f Info DO 
BEGIN 
SELF .fltemHeight := ascent + descent + leading + 1; 
SELF .fLineAscent := ascent + (leading DIV 2) - 1; 


I 


END; 


( Set up the pen for drawing the characters; assumes that we 
are focused on the correct window Cor a frame in the correct 
window); this is a method so it can be overridden easily } 
PROCEDURE TListView.SetPen; 
BEGIN 
PenNormal; 
TextFont(SystemFont); 
TextSize( 12); 
TextFace([]); 


) 


( Create a rectangle, for this item. ) 
FUNCTION TListView.SetUpBoxCindex: INTEGER): Rect; 
VAR bBox: Rect; 
BEGIN 
( use same left and right es view, calculate the top end 
bottom for this item number) 
WITH bBox DO 
BEGIN 
left := SELF.fExtentRect. left; 
top := (index - 1)* SELF .f ItemHeight; 
( Subtract 1 to get the TOP line ) 
right := SELF .fExtentRect right; 
bottom := top + SELF.f ItemHeight; 


END; 
SetUpBox := bBox; 


4 


END. 


( TwoLineList View unit which is used in a variant of the 
MacApp QuadWorld Application. 
Copyright 1986 by Productivity Products International, Inc. ) 


UNIT UTwoL ineListView; 
INTERFACE 


USES 
( This set of units are portions of the Macintosh ROM ) 
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 


( This set of units are portions of MacApp ) 
U0bject, UList, UMacApp, UListView; 


TYPE 
TTwoLineListDocument = OBJECTCTListDocument) 
{ an abstract superclass that contains methods 
needed for the proper use of a two-line list view ) 
( No additional instance variables ) 
FUNCTION 
TTwoL ineL istDocument .Repor tCoordinateStr ing 
CitemNumber: INTEGER): Str255; 
END; (of TTwoLineListDocument ) 
TTwoLineListView = OBJECTCTListView) 
( No additional instance variables ) 
PROCEDURE TTwoL ineListView.DrewOneItem 


Citem: Str255); OVERRIDE; 
PROCEDURE TTwoLineListView. 
SetItemHeightAndLineAscent; OVERRIDE; 


END; ( TTwoLineListView ) 
IMPLEMENTATION 
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( *** TTwoLineListDocument (en abstract superclass ) ** } 


FUNCTION TTwoL ineListDocument .Repor tCoordinateStr ing 
CitemNumber: INTEGER): Str255; 


BEGIN 
($IFC qDebug) 
ProgramBreak('Call to TTwoL ineListDocument. 
ReportCoordinateString- an abstract Superclass'); 
($ENDC) 


END; 


( RXXXXAAARERERRRK = TTwoL ineListView XXXXXXXXEXEXxX) 


( Drew one item which consists of two lines. Use the 
overridden procedure to draw the first line and then augment 
with the code to draw the second line. ) 

PROCEDURE TTwol IneListView.DrawOnel tem 

Citem: Str255); OVERRIDE; 

VAR myDocument : TTwoL ineL istDocument ; 

BEGIN 
INHERITED DrewOneItemCitem); 
MoveC-StringWidthCitem), SELF .fItemHeight DIV 2); 


myDocument := TTwoLineListDocument 
(SELF . fDocument); 
DrawStr ing(myDocument .Repor tCoordinateStr ing 


(SELF .fCurrentItem)); 
END; 


( Double the item height for a two-line item. ) 
PROCEDURE TTwoLineListView. 


SetI temHe ightAndL ineAscent; OVERRIDE; 
BEGIN 


INHERITED SetI temHe ightAndL ineAscent; 
SELF .fItemHeight := 2*SELF.fItemHeight; 


4 


END. 


( MiniIcon ListView unit which is used in a variant of the 
the MacApp QuadWorld Application. Copyright 1986 by 
Productivity Products International, Inc., for MacTutor. ) 


UNIT UMiniIconListView; 
INTERFACE 


USES 
( This set of units are portions of the Macintosh ROM ) 
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 


( This set of units are portions of MacApp ) 
UObject, UList, UMacApp, UListView; 


TYPE 
TMinilconListDocument = OBJECTCTListDocument) 
( en abstract superclass that contains methods 
needed for the proper use of a mini-iconlist view ) 
( No additional instance veriables ) 
FUNCTION TMiniIconListDocument .Repor t IconNumber 
CitemNumber: INTEGER): INTEGER; 
END; (of TMinilIconListDocument ) 
TMinilconListView = OBJECTCTListView) 
{ No additional instance variables } 
PROCEDURE TMinilconListView.DrawOnel tem 
Citem: Str255); OVERRIDE; 
END; ( TMiniIconListView ) 
IMPLEMENTATION 
{ *** TMinilconListDocument (an abstract superclass ) *** } 
FUNCTION TMiniIconListDocument. 
ReportIconNumber(CitemNumber: INTEGER): INTEGER; 
BEGIN 
($1FC qDebug) 
ProgramBreak('Call to TMinilconListDocument. 
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ReportIconNumber- an abstract Superclass'); 


($ENOC) 
END; 


( **xxiirrxkxxxxxX TMinilconListView  XXxxxxxixrtdooex ) 


( Drew an icon first, then drew the text string ) 
PROCEDURE TMiniIconListView.DrawOneItem 


Citem: Str255); OVERRIDE; 


( Drew the mini-icon ) 
PROCEDURE DrawIcon; 
VAR tempRect: Rect; 
tempHandle: Handle; 
myDocument: TMiniIconListDocument; 
BEGIN 


( The rectangle into which the icon will be drawn ) 
tempRect :- SELF . SetUpBoxCSELF . f CurrentItem); 


tempRect.right := tempRect.left + 


SELF. f ItemHeight; 


( Get the icon ) 
myDocument := 


TMiniIconListDocument(SELF . fDocument); 


tempHandle := 
Get IconCmyDocument .Repor t IconNumber 


(SELF . fCurrentItem)); 


FailNILCtempHandle); 

( Drew the Icon ) 
PlotIconCtempRect, tempHandle); 
END; 
BEGIN 

DrawIcon; 
Move(SELF .f ItemHeight, Ø); 
INHERITED DrewOneItemCitem); 


/ 
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"m-[—7 


—— T BOLT 


| Break at [Typename.ProcName or ProcName1? TMini IconLis 
d Trace OFF; Break set at TMINIICO.REPORTHI 

] Now at BEGIN CHECKDES # 6 

B go... 


APPS EEE ONAN E NE ARAS 


eO @ cec cec oii 


Hi 
[] 


oo 
~~ = 


Fig. 4 Free Debugging Help with MacApp 


Pascal Procedures 
Introduction to Object Pascal 


Introduction | 

If you have been reading about MacApp, you may be 
wondering if you have to have the Macintosh Programmer's 
Workshop (MPW) and if MacApp programs must be written 
in Object Pascal. The answer is yes, for now. For those of 
you who like some of the other Pascal compilers out there, or 
prefer to program in another language such as C, you are 
currently out of luck. The reason is two-fold. Most 
languages for the Macintosh do not support the object-oriented 
concepts upon which MacApp so heavily relies, and even if 
they do, they don't use the same run-time scheme that Object 
Pascal does. 

In this article I will first present a description of the 
syntax of Object Pascal and comment on some of the 
semantics involved in using the syntax. I will discuss the 
various degrees of compatibility that another language or 
compiler needs to achieve in order to make use of MacApp and 
what steps are necessary in meeting that goal. In particular, 
the exact format of the generated code and the run-time 
routines that deal with that code will be shown. I will talk a 
bit about how we added objects to MPW's Assembly 
language. Finally I present a scheme for optimizing what 
we ve already learned. 

Object Pascal 

Object Pascal is an extension to the Pascal language that 
was developed at Apple in consultation with Niklaus Wirth, 
the inventor of Pascal. It is descended from an earlier attempt 
at an object-oriented version of Pascal called Clascal, which 
was available on the Lisa computer. MacApp itself is 
descended from the Lisa Toolkit, an application framework for 
creating Lisa applications. The Lisa Toolkit was written in 
Clascal. 

There are actually very few syntactic additions to Pascal 
in Object Pascal. A new data type is added, the object. An 
object is very much like a record in that it can have multiple 
data fields of arbitrary types. In addition, you can specify a 
list of procedures and functions, referred to as methods, for a 
particular object type. These methods define the actions that 
an object of this type can perform. For example, you could 
define a Shape object type as follows: 

type 

Shape = object 
bounds: 
color: 
procedure Draw; 
procedure Erase; 
procedure RotateCangle: integer); 
procedure Move(delta: Point); 
function Area: integer; 

end; 

Furthermore, you can define an object type that inherits 
the fields and methods of another object type. The new type 


Rect; 
Pattern; 
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can define additional fields and methods and can choose to 
selectively override methods that it has inherited. 
type 
Circle = object(Shape) 
radius: integer; 
procedure Draw; override; 
function Area: integer; override; 
procedure SetRadius(newRadius: integer); 
end; 


var aCircle: Circle; 

An object type is often referred to as a class. In the 
above example, Circle is a subclass of Shape. Shape is the 
superclass of Circle. A class (object type) can have many 
subclasses (descendants), but only one superclass (immediate 
ancestor). When speaking of the relationships conceptually , I 
will more often use the class terminology. When speaking in 
terms of Pascal data types I use the object type terms. 

Objects are created by calling the Pascal built-in 
procedure New on a variable of an object type. You say 
New(aCircle) to create an instance of the object type Circle. 
The New procedure, when used with an object type variable 
allocates sufficient storage on the heap for the object and sets 
the value of the variable to be a handle (pointer to a pointer) to 
that data. The double arrow normally required for handle 
dereferencing is done automatically by the compiler, so fields 
are accessed directly, eg: — aCircle.bounds, NOT 
aCircle^^.bounds. Likewise, to invoke a method you use the 
same notation: aCircle.Draw invokes the Draw method of the 
Circle object type, presumably drawing itself on some display. 
Since all object type variables are actually handles to the data, 
an assignment such as shapel := shape2 causes shapel to 
point to the same data as shape2. 

The fields of an object can themselves be references to 
other objects. For example you could have a nextShape field 
in the Shape definition if you wanted to have a linked list of 
shapes. Object Pascal allows you to specify the type of a field 
to be a reference to an object type not yet declared. In this 
manner, you can have circular references of object types to one 
another. If the compiler encounters an undeclared type 
identifier, it assumes it is an object type that will be declared 
later. If the type is not declared later, an error will be reported. 
The size of the not yet declared object is unimportant since the 
reference to it is always just a four byte handle. 

The depth to which an object type can inherit is 
unlimited. You could define a descendant of Circle and another 
descendant of that type and so on. Each succeeding descendant 
inherits all of the fields and methods of all of its ancestors. 

Object Pascal requires that the object type definitions be 
at the highest level in a unit or program, always as a type 
declaration. For a unit this can be either in the interface or the 
implementation part. The body or actual code for the methods 
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appears in the procedure and function part of the unit or 
program. If the body of a declared method does not appear in 
the file, the compiler issues a "method not implemented" 
error. The body of a method is just like that of any procedure 
or function: 


procedure Shape.Erase; 
begin 

EraseRect (bounds); 
end; 


procedure Circle.Draw; 
begin 
Fill0valCbounds, color); 
FrameOval (bounds); 
end; 
There are several things to note in these two examples. 

The name of the method is given as TypeName.MethodName 
to distinguish which method is being defined. When inside a 
method, there is always an implicit parameter called SELF. 
SELF refers to the object that invoked the method. The fields 
of the object could be accessed as SELF.bounds or 
SELF.color, however the compiler provides an implicit "with 
SELF do" block around the method making the field names 
directly accessible. Similarly, you could invoke another 
method from within a method by saying SELF.OtherMethod 
but again just OtherMethod is sufficient. This obviates the 
need for SELF other than when one wishes to pass the object 
itself to another routine, eg: AddMeToList(SELF). For the 
statement aCircle.Draw, since aCircle is of type Circle, the 
Circle.Draw method would be called rather than the 
Shape.Draw method. In addition, if the aCircle.Erase is called, 
since Circle did not override the Erase method, the Shape.Erase 
method would be invoked. This is fairly straightforward. 
Slightly less obvious behavior occurs if the following code is 
executed: 

var aShape: Shape; 

aCircle: Circle; 


NewCaCircle); 
aCircle.bounds := someRect; 
aCircle.color := white; 
aCircle.radius := 60; 
aShape := aCircle; 

aShape .Draw; 

When aShape.Draw is executed, which method is called: 
Shape.Draw or Circle.Draw? Even though aShape is declared 
as a Shape, the assignment to aCircle causes it to be a Circle 
object and thus Circle.Draw would be the method called. This 
is accomplished by means of a two byte type identifier at the 
beginning of every object (see Figure 1). This raises some 
important points. The assignment aShape :- aCircle is "safe" 
because any fields or methods accessed for a Shape object will 
be valid for a Circle object. But the reverse assignment 
aCircle := aShape is not safe since the additional fields or 
methods in Circle will not necessarily be understood by a 
Shape object. For example, if we later tried to invoke 
aCircle.SetRadius it would not be understood had aShape been 
a regular Shape object. (In fact, the aShape variable could have 
referred to an entirely different descendant of Shape, say 
Triangle, which also would not understand any Circle-specific 
methods calls or field accesses.) The compiler issues an error 
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message if such an assignment is attempted. If you are 
absolutely sure that in this case the Shape variable is 
guaranteed to be pointing to a Circle object, you can use 
coercion to override the compiler: aCircle := Circle(aShape). 
Even then, at run time, if range checking is turned on, the 
assignment will be checked to make sure it is valid. 

The point to remember from this is that even though a 
variable is declared to be of a particular object type, at run 
time, its actual type may be that type or any descendant of that 
type. It is by this means that one could have a list if "shapes" 
that could each be told to "draw", where the actual types are a 
mixed collection of circles, squares, triangles, and so forth. 
As a result, the determination of which actual method to call 
must be made at run time. This is accomplished using a 
“method dispatch routine" that looks at the two byte type field 
of the object and uses tables of method locations to direct the 
call to the proper method. Method dispatching will be 
discussed in more detail later. 

A final syntactic addition to Pascal is the inherited 
keyword. If you have overridden a method to add some code 
specific to your object type but still want to use the code in 
the overridden method, you would use the word inherited 
followed by the method name: 

var aCircle: Circle; 


aCircle 
master pointer 


Figure 1 


procedure MyController .ProcessKeystroke(ch: char); 
begin 
if ch = 'X' then 
DoSomethingSpecial 
else 
inher ited ProcessKeystroke(ch); 

end; 

Assuming Controller was the immediate ancestor of 
MyController, the inherited call would be a call to 
Controller.ProcessKeystroke (given that the method exists). 
In the case of inherited, the proper method to call can always 
be determined at compile time -- there is no need for a run 
time method dispatch. The call is always to the closest 
ancestor that implemented the method. Realize that this does 
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not necessarily mean the immediate ancestor. If the immediate 
ancestor did not implement the method but an ancestor further 
up in the hierarchy did, the call would be to that method. By 
using the inherited keyword rather than explicitly naming an 
ancestor (superclass) object type, you are insulated from 
possible future changes that might insert or delete an 
implementation of the method in an ancestor or superclass. 
The compiler will issue an error message if inherited is used in 
a method that was not inherited from an ancestor object type. 

Object Pascal also provides the built-in function 
Member. You can use Member to test if a particular object is 
in a certain class. For example you could say: 

if MemberCaShape, Circle) then 
numCircles := numCirclest]; 

Member returns true if the object's type is the same type 
or a descendant of the object type being tested. In the example 
above, numCircles would be bumped for ordinary circles and 
any specialized subclasses of Circle, but not for Squares, 
Triangles, or ordinary Shapes. The use of the Member 
function is somewhat contrary to the principles of object- 
oriented programming (you're not supposed to peek at your 
own type) so its use is generally discouraged except in unusual 
circumstances. 

Since all object references are stored as handles to the 
object data on the heap, there are a couple of Pascal constructs 
that are unsafe to use on fields of an object. One is the use of 
a field as a VAR parameter in a procedure call. The Pascal 
compiler pushes the address of a VAR parameter on the stack. 
If the heap were to compact while processing the procedure, 
the address of the field of the object could become invalid. 
Another situation where the compiler computes an absolute 
address is if you use the with statement on an object field that 
is a record type, eg: "with aCircle.bounds do". If some 
statement in the with block caused a compaction, the 
computed address could become invalid. The compiler issues 
warnings when such a usage is detected. If you are sure the 
procedure or with statement will not compact the heap, you 
can precede the statement with the ($H-) compiler option. 
This tells the compiler not to issue the warning. You should 
follow the statement with ($H-) to turn heap warnings back 
on. 

Levels of Compatibility 

If you are a compiler writer who wants to use MacApp, 
there are a variety of levels of compatibility you can strive to 
achieve. The degree of compatibility can fall into the 
conceptual, the source file, or the object file level. (Note: The 
term object is used in two completely different contexts in this 
article. One use is with object-oriented phrases such as object 
type or an object on the heap. The second use is when 
speaking of the object file format, which is the term used for 
the structure of a file generated by a compiler.) To be 
conceptually compatible, the language must support the object- 
oriented concepts of object type definitions, inheritance, and 
method calls. Source file compatibility is a special case that 
only applies to Pascal compilers. The Pascal compiler would 
have to support all of the extensions to Pascal that the 
Macintosh Workshop Pascal supports, which in addition to 
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the object-oriented extensions, includes such features as 
separately compiled units, expressions in constant 
declarations, and numerous compile time options such as 
conditional compilation. Finally, languages that are object 
file compatible would use the same object file format, namely 
that defined in the appendix of the MPW reference manual, and 
furthermore would support the specific method calling 
conventions and method table formats that Object Pascal 
generates. 

If a language supports the object-oriented concepts of 
Object Pascal and if the programming structures of the 
language resemble the structures of Pascal, it should be fairly 
simple to write a program to do an automatic translation of 
MacApp into the desired language. For known constructs that 
are not automatically translatable, the program would flag that 
code for hand translation. The compiler writer could then 
distribute either the translated source or the compiled object 
form of MacApp, subject, of course, to whatever legal mumbo 
jumbo is required from Apple to redistribute MacApp. For 
compilers that do not use the MPW object file format, some 
variation of this will be the only alternative for those who 
want to use MacApp. 

Pascal compilers that add the extensions of Macintosh 
Workshop Pascal can directly compile the MacApp sources 
themselves. If your compiler supports most but not all of the 
extensions, you may be able to modify the MacApp source 
files to not use the unsupported features. The object-oriented 
extensions would, of course, have to be supported. 

Compilers that generate code using the MPW object file 
format and use the Object Pascal method table and method 
calling schemes will be able to link directly with compiled 
MacApp files. They will be able to link with Object Pascal 
building block files such as the Text and Dialog Box units. 

Currently, most compilers do not support the MPW 
object file format. Hence, the only option available is that of 
translating MacApp into their particular language (which may 
be a trivial or null translation in the case of Object Pascal 
compatible compilers). If you as a compiler writer are not 
religiously (or pragmatically) devoted to your particular object 
file format, I would encourage you to consider using that of 
MPW. In any event, the discussion of our particular method 
table organization and method dispatching scheme that follows 
should be useful if you are considering adding object-oriented 
features to your language, even if you decide to implement 
your language in a completely different way. 

Object File Format 

As mentioned before, Apple's Object Pascal compiler 
generates files using the MPW object file format. The 
Structure of the file consists of a collection of varying length 
records. There are eleven different kinds of records. The 
important ones for our purposes are the module, contents, and 
reference records. The module record specifies a new code or 
data module. Each procedure or function is represented by a 
code module. It is generally followed by one or more reference 
and/or contents records. The reference records specify what 
external modules are referenced from the current module. The 
contents records contain the actual code of the routine. The 
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linker uses the reference and module records to patch branches 
and other instructions that have external references. 
The Class Info Proc 

When an object type is defined, a phony code module is 
generated. This code module is known as the "Class Info 
Proc". It contains information on who the ancestor is, what 
the size of an object of this type will be, and how many 
methods are implemented by this type.: This is followed by 
the actual method table. This module is never actually called. 
It is placed in a special segment named %_MethTables with 
all other class info proc's. This segment also contains a very 
short routine called %_RTS1. The code for it is simply an 
RTS instruction. At application startup, %RTS1 is called, 
which loads the segment with all of the method tables. 

The Method Call 

Before I talk about the format of the method table itself, 
we need to understand how a method call works. Consider the 
following method call: 

aShape .MoveCdist); 

Method calls in Object Pascal naturally use Pascal calling 
conventions. First the parameters are pushed onto the stack 
(in the order they appear in the procedure declaration), then a 
JSR (Jump to Subroutine) call is made. Recall that in a 
method, there is always the implicit parameter SELF. This is 
pushed onto the stack after the actual parameters of the 
method. The object code for the method call above will look 
somewhat like this: 

MOVE.L dist,-CSP) 
MOVE.L aShape,-CSP) 
JSR ?? 

Where does the JSR jump to? Since the actual method to 
call is dependent on the run time type of aShape, we cannot 
put a direct JSR to Shape.Move. At run time, aShape could 
be a Circle, Square, or some descendent not even known when 
this code was compiled. We need to go through a dispatch 
mechanism that examines the object to determine its type and 
then call the appropriate method based on that type. But so 
far, looking at the code above, we haven't even indicated what 
method we want to call. Most object-oriented languages use 
the selector technique to indicate to the dispatching routine 
what method is being called. A selector is some unique 
identifier for a particular method name. Often the selector is 
simply the name of the method itself. This, however can be 
expensive in terms of space required. Furthermore, Object 
Pascal allows methods in unrelated branches of the object 
hierarchy to have the same name with completely different 
parameter lists. The compiler treats these as totally separate 
method definitions. Simply using the method name for the 
selector would be ambiguous. 

The Selector Proc 

The question remains: how do we generate a unique 
selector for each method name? We let the linker do it! The 
linker, in resolving cross segment references, patches JSR's by 
having them branch into a jump table that then jumps to the 
correct routine. When segments are unloaded and reloaded in 
memory, the jump table entries are updated appropriately. The 
jump table is stored near an address pointed to by register A5. 
All JSR's into the jump table are of the form JSR x(A5) 
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where x is some offset into the jump table. It is this offset x 
that the linker generates that we use as the method selector. 
As each new method name is encountered during the 
compilation of an object type definition, a very short 
procedure is generated. This procedure is referred to as the 
"selector proc". Its name is of the form 
TypeName$MethodName, such as Shape$Move. Note that 
the selector proc is not generated for method Overrides, only 
when the method definition is first encountered. Methods by 
the same name in an unrelated branch of the hierarchy would 
have a selector proc, for example Employee$Move. The 
contents of the selector proc is simply a JSR to the actual 
method dispatching routine, called % Method. 

It is to the appropriate selector proc that all method calls 
are directed. The JSR instruction above would therefore be 
JSR Shape$Move. All selector procs are placed in another 
special segment, "%_SelProcs". All references to it are 
guaranteed to be through the jump table. The critical 
significance of this is that when the JSR is patched by the 
linker, the two-byte offset into the jump table is unique for 
that method name. The method dispatch routine examines 
those bytes and matches them against values stored in the 
method tables to determine what method is being called. 
Which brings us back to the format of the method tables. 

Method Table Format 

As mentioned above the method table for a particular 
object type appears at the end of the class info proc. The table 
is simply a list of pairs of references, one pair for each method 
implemented by this type. The first reference in each pair is 
to the selector proc and the second is to the actual method 
implementation. Each of these references are guaranteed to be 
across segments. Normally, when the linker is resolving a 
cross segment reference, it not only patches the offset bytes of 
the instruction, it also sets the bits in the instruction itself to 
make it A5 relative. For the method tables, there are no 
JSR's, just offsets that need to be patched. Fortunately there 
is a special bit (the A5-relative flag) in the reference record to 
tell the linker not to attempt to edit the word before the offset 
location. 

Objects on the Heap and the New Routine 

Objects are created using the New procedure. The 
compiler detects whether the parameter is an object type 
variable. It calls a quite different procedure than the normal 
New for pointer types. This procedure, % OBNEW, allocates 
the data on the application heap. (Normal pointer New calls 
get data allocated on a special Pascal Heap.) %_OBNEW must 
also set the two byte class identifier field for the object. Like 
almost every other two byte field we've seen so far, this is an 
AS offset into the jump table. This time the reference is to 
the class info proc of the class of the parameter to New. The 
actual calling sequence for New(aCircle) is: 


PEA aCircle 

PEA Circle's Class Info Proc * 2 
MOVE.W "size of instance,-CSP) 
JSR $ OBNEW 


The "+ 2" for the class info proc is somewhat of a hack. 
The jump table entry for the class info proc is JMP x where x 
is the address of the class info proc. We don't want to execute 
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the code there, we just want to look at the information in it. 
By bumping the pointer by two we are in effect creating a 
handle to the class info proc, where the master pointer is the 
address stored after the JMP instruction in the jump table. 
% _OBNEW calls a routine %_SetClassIndex that subtracts A5 
from this "handle" and stuffs the result into the two byte type 
identifier field. When a method is called, %_Method adds A5 
back to the two byte field of the object, thus reconstructing 
the handle to the class info proc. 
The Method Dispatch Routine 

In Figures 2 and 3 we see how a typical method call 
works. As we saw before, the parameters of the method, if 
any, are pushed onto the stack followed by the handle to the 
object itself. We then do a JSR to the selector proc, in this 
case Shape$Rotate. Shape$Rotate, like all selector procs, is 
simply a JSR to %_Method, the dispatch routine. In the 
method dispatch routine we first grab the handle to the object 
from the stack. We then extract the class identifier bytes from 
the object header. Adding AS to these bytes gives us a handle 
to Circle's class info proc. The method "selector" is the two 
offset bytes after the JSR instruction to the selector proc. We 
search through the method table in the class info proc for a 
match to this selector. Since Rotate is not overridden in 
Circle, we do not find a match in this table. We then find the 
class info proc of the superclass, namely that of Shape. We 
go through the same search for the method selector and this 
time we do find a match for Rotate. We then jump to the 
proper routine, Shape.Rotate. 

Type Checking 

Previously I mentioned that if you use type coercion to 
do an assignment of one object type variable to another, a run 
time check would be generated. The check is to see if the type 
of the object being assigned is the same type or a descendant 
type of the variable on the left side of the assignment. This is 
the same check that is made when you call the Member 
function. The routine that does this is called %_OBCHK. It 
takes two parameters, a handle to the object and a pointer to 
the jump table entry of the class info proc for the class whose 
membership is being tested. %_OBCHK returns the object 
handle if the test succeeds and nil if it fails. It calls the 
routine boolean routine %_InObj to do the actual test. 

The information presented thus far should be sufficient 
for someone to implement object-oriented features in their 
language. The following discussion of "Object Assembler" is 
an example of how we took another "language" and generated 
the same method table formats and so forth to create an object 
file compatible alternative to programming exclusively in 
Object Pascal. 

Object Assembler 

Despite the many advantages of using a higher level 
language, we wanted to be able to escape to assembly 
language when necessary to efficiently code-time critical parts 
of an application. Using the powerful macro language 
available with the MPW 68000 Assembler, I was able to write 
a set of macros that allows one to define a class, implement 
and call methods, and create new objects, all in 68000 
assembly language. 
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For example, the Shape and Circle definitions we saw in 
Pascal would look like: 
ObjectDef Shape,, \ 
(bounds, 8), \ 
(color,2), \ 
METHODS, —. 
(Draw), —. 
(Erase), 
CRotate), \ 
(Move), \ 


Sample Method Call: aShape.Rotate(angle) 
(where aShape is currently a Circle object) 


Push angle 
Push aShape 
JSR Shape$Rotate 


o The two byte offset for this JSH 
o instruction is the method 
selector that is searched for in 


Shape$Rotate: the method tables in Fig 3. 


JSR %_Method 


o 
o 


9e Method: The Method Dispatch Routine 


Use method call return address to get Shape$Rotate A5 offset 
Use class field of receiver to find Method Table 
Scan method table for Shape$Rotate A5 offset 
If found: Jump to Circle.Rotate 
If not found: Find SuperClass (Shape) Method Table 
and repeat scan 


Fig. 2 


(Error condition detected if the object is NIL or method not found) 
(Area) 


0bjectDef Circle,Shape, \ 

Cradius,2), \ 

METHODS, \ 

(Draw, OVERRIDE), \ 

CArea, OVERRIDE), \ 

(SetRadius) 

(The N character is required by the Assembler when 
continuing a line) 

The ObjectDef macro actually generates the class info 
proc and selector procs as specified earlier. It also sets up data 
structures for allowing field accesses and method calls later in 
the code. A method is defined as follows: 

Erase: ProcMethOf Shape 
LINK 50,46 
MoveSelf AQ 
MOVE.L (A02,A0 
PEA — bounds(CA2) 
-EraseRect 
UNLK A6 
MOVE.L (CSP), (SP)+ 
RTS 


EndMethod 

The ProcMethOf macro (and the FuncMethOf macro) 
invoke another macro, ObjectWith, that allows field references 
like bounds(AO) to work properly. MoveSelf is a simple 
macro that gets SELF off of the stack. It assumes that you 
started the method with a LINK A6. The routine above loads 
SELF into AO, dereferences it, and pushes the bounds field 
onto the stack so that EraseRect can be called. After the 
Unlink, the stack is fixed up by stuffing the return address on 
top of the single parameter, SELF, and the method returns. 
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a Circle object 


Class identifier 


instanceSize 


Area selector 


JT = Add two byte value to A5 
to get offset into Jump 
Table where address of 
table or routine will be found 


ACircle.SetRadius 


Method calls are made using the MethCall macro: 
MoveSelf -CSP) 
MethCall Draw, Shape 
MethCall generates a JSR to the proper Selector proc for 
Draw. If the call was made from inside of a method of Shape 
or a subclass of Shape, the parameter Shape could have been 
omitted. The other important macros are Inherited and 
NewObject: 


MoveSelf -CSP) 
Inherited Draw 


NewObject 10CA6),Circle 

Inherited behaves as in Object Pascal. NewObject 
requires a memory reference parameter and a type name. The 
handle of the new object is stored into the memory location 
specified by the parameter. 

A full description of the macros available is contained in 
both the MPW Assembler Manual and the MacApp Reference 
Guide. Since these macros generate the same code that Object 
Pascal does, any code written in "Object Assembly" language 
can be linked with MacApp object files. In fact, specific 
methods in Object Pascal can be declared external and coded in 
assembly language using the macros. In addition, the 
assembled files can be run through the Optimizer described in 
the next section. 

The Optimizer and the New Run Time 
Environment 
In running sample applications written in MacApp, the 
performance has been quite good, despite the fact that every 
method call must go through the method dispatch mechanism 
before being executed. However, we realized that some 
significant optimizations were possible once the entire object 
type hierarchy was known. We have developed an optimizer 
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Circle Class Info Proc 


superclass 

(12) 

numMethods (3) 
Draw selector 


^Circle.Draw 


^Circle.Area 


SetRadius selector 


Shape Class Info Proc 


superclass (0) 
instanceSize (10) 
numMethods (5) 

Draw selector 

^Shape.Draw 

Erase selector 

^Shape.Erase 

Rotate selector 


^Shape.Rotate 


C 
EI 


Move selector 


^Shape.Move Shape.Rotate: 


Area selector <code> 


^Shape.Area 
Fig. 3 


program that processes the object files just before they are 
linked. It builds an internal representation of the entire object 
type hierarchy and proceeds to analyze it for potential 
optimizations. 

Treatment of Monomorphic Methods 

The most significant savings arises from being able to 
identify those methods that are implemented in only one 
object type, in other words, methods that are never overridden. 
Since these "monomorphic" methods have only one 
implementation, there is no need for a call to them to go 
through method dispatching. The Optimizer reroutes calls to 
these methods to jump directly to the method. Recall that 
originally the call was to a "selector proc" that in turn called 
the method dispatch routine. Not only does this increase the 
speed dramatically for these method calls but the space required 
is reduced. There no longer needs to be a selector proc nor the 
jump table entry that pointed to it. Also the entry in the 
method table for that method can be eliminated. 

We have found that approximately 75% of the methods 
defined in MacApp applications are monomorphic. These 
include many internal methods of the MacApp classes 
themselves. For any "leaf" object type, one that has no 
descendants, any new method it defines will be monomorphic. 

Transposition of the Method Tables for 
Polymorphic Methods 

For the remaining "polymorphic" methods, those 
methods that are implemented by more than one class, the 
now reduced method tables are transposed. That is, where 
before each method table was a list of the methods 
implemented by a particular class, now each table is a list of 
classes that implement a particular method. This results in 
more tables of shorter length. Previously the method tables 
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were stored in the class info procs. Now the tables are stored 
in the selector procs. In fact, they are stored immediately after 
the JSR instruction that jumps to the method dispatch routine. 
Thus the address of the method table is on the top of the stack 
when the dispatch routine is entered. 

The form of this new method table is a list of two byte 
pairs. The first element in the pair is a class number that is 
generated by the optimizer. The second element is a reference 
to the actual implementation of the method, which the linker 
has patched with an AS offset into the jump table. (This 
element is unchanged from the previous method table format.) 
The class number of a particular class is always greater than 
that of its superclass. The entries in the method table are 
sorted in descending order of class number. By numbering the 
classes in this way and keeping a separate table of 
superclasses, the method dispatch routine can properly search 
the method table. A Class number is always an even positive 
integer, making accesses to the superclass table simpler. A 
handle to the superclass table is stored in a low memory 
location. 

The New Object Header 

In the optimized run time environment objects have a 
different two byte class identifier than before. The A5 offset 
to the jump table entry of the class info proc is replaced by the 
class number that was generated by the optimizer. The class 
info proc no longer contains the method tables or a reference 
to the superclass. In fact it has just a single two byte entry, 
namely the class number. The calling sequence to 
90 OBNEW is the same as before, but the Optimizer actually 
redirects the 96. SetClassIndex call in 90 OBNEW to instead 
call %_OptSetCI. %_OptSetCI gets the class number from 
the class info proc and stuffs it into the object header. 

The New Method Dispatch Routine 

The new method table format requires a new method 
dispatching scheme. In fact, this is the scheme used by the 
method dispatch routine in the 128K ROM. The routine is 
also available in the libraries for 64K ROM machines. 

A somewhat complicated algorithm is used to check only 
those methods that belong to the hierarchy of the object 
processing the method. For example, following the example 
in Figures 4 and 5, if aShape.Rotate was called and aShape 
was currently a Circle object the search would proceed as 
follows. First check to see if the most recent search was for a 
Circle by checking the cache at the beginning of the table. If 
we get a match, we jump immediately to the method (via the 
cached jump table offset). If we don't get a match, then check 
each entry in the table until we do get a match OR we arrive at 
a class number that is less than the current number. Since the 
current number is 8, we will skip the 10 (square.rotate) and 
stop at 6 (triangle.rotate). If we match, we jump to the 
method. It isn't a match, so now we look up Circles 
superclass in the superclass table. The superclass is 4 (shape), 
and we proceed as before searching for a match or a number 
less than the current number (now 4). The next entry is a 4 so 
we match. Before jumping to the method, we stuff the 
original class number 8 in the class number cache and the 
jump table offset for shape.rotate in the method cache. If the 
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next call to Rotate is for a circle object we'll get an immediate 
hit in the cache. 

The Optimizer also redirects the %_InObj routine to 
96 OptInObj. This is the boolean function that tests object 
membership in a particular class. The new routine uses the 
class number of the object and the superclass table to test the 
object. 

Future Optimizations 

Other optimizations are possible when the entire class 
hierarchy is known. Say a variable aCircle is declared to be of 
type Circle and furthermore that there is no descendant of 
Circle defined. Then any method call that aCircle makes can 
be resolved before run time. This is because any object type 
variable can only reference an object whose type is the declared 
class or a descendant of that class. Since Circle has no 
descendants we know that aCircle must be a Circle object. 
Therefore we know that if Draw is invoked, we should call 
Circle.Draw and if Erase is invoked we call Shape.Erase (since 
Circle did not implement Erase) and so on. This is a little 
more difficult to implement and has not yet been put into the 
Optimizer. 

Supporting the MacApp Debugger 

One of the most appealing features of MacApp is its 
powerful debugger. The debugger is independent of the object- 
orientedness of MacApp. When an application is compiled 
with debugging flags turned on, the MacApp debugger is 
installed in a separate window on the screen. At any time 
while running the application you can go into the debugger 
and look at the stack or see a recent history of procedure calls. 
You can examine objects on the heap and even set up 
intentional error conditions such as nil object handles. You 
can set break points at specific methods and you can step 
through the code a method at a time. There are many other 
useful features. 

To support the debugger, the Object Pascal compiler 
inserts a call to a special routine called BP at the beginning of 
every routine. It also inserts a call to EP at the end of every 
routine and a call to EX for Exits or GOTO's that jump out of 
a routine. In addition, the name of each routine is appended 
after the code of the routine. BP, EP, and EX are implemented 
in the UTrace unit that comes with MacApp. If you want to 
support the MacApp debugger, you should look at how it 
works and see if you can tailor it to your particular language. 

The C4- Language 

We at Apple are anxious to see more compilers support 
object-oriented concepts and be able to make use of the several 
man-years of effort that went into developing MacApp. In 
particular we recognize the popularity of the C language and 
the proliferation of C compilers available on the Macintosh. 
Since the C compiler that comes with MPW was done by a 
third party and they were under considerable time pressure to 
deliver as it was, we were not able to get object-oriented 
features put into it. 

In the meantime, however, we have come up with a 
recommended specification for an object-oriented C. It is 
based on the C++ language from Bell Labs. It is essentially a 
subset of C++ that includes just those features necessary to 
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Optimized Method Call: aShape.Rotate(angle) 
(where aShape is currently a Circle object) 


Push angle 
Push aShape 
JSR Shape$Rotate 


The optimized method tables 
now appear immediately after 
the call to the dispatch routine 


Shape$Rotate: 
JSR %_OptMeth 


Meth Table 


0 
o 


%_OptMeth: TheOptimized Method Dispatch Routine 


Use Shape$Rotate return address to get address of method table 
Set current id to class id of object 
Scan method table until class id <= current id 
If equal: Set cache and Jump to Circle.Rotate 
If class id « current id: Set current id to Superclass id from 
Superclass Table and repeat scan 


Fig. 4 


(Error condition detected if the object is NIL or method not found) 


support MacApp. We call this language C+-. The 
specification is available as a technical report from the Apple 
Library. Of course, if you want to support the full C++ 
specification, you will still be compatible with C+-. 
How to Get Help 

If you do decide to use some of the information presented 
in this article in order to be able to use MacApp, contact 
Harvey Alcabes at Apple. Harvey is the Product Manager for 
MacApp and is coordinating third party efforts to add objects 
to their languages. He can advise you on any licensing 
requirements for distributing translated versions of MacApp 
and so forth. 
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Superclass table 


a Circle object 
i text 
Class id 8 not 
found in method shape 
table so try its triangle 
superclass 
circle 
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Basic School 


Scroll that Window in Basic! 


One of the problems of using 
BASIC as a programming 
language is the inability to access 
the Macintosh ROM routines. 
Many of the toolbox and graphics 
functions — are built into 
MSBASIC (2.0 or later) such as 
MENU, WINDOW, EDIT 
FIELD, BUTTON which we 
have covered in prior issues of 
MacTutor. This month we will 
discover the use of some 
specialized LIBRARY routines 
which make use of Macintosh 
ROM routines which before this 
time were only accessible to other 
programming languages (C, 
Forth, 68000 Assy., and others). 

The routines which are 
featured in this month's column 
come from Clear Lake Research of 
Houston, Texas. It should be 
noted that the program and 
discussion which follows will not 
work without the Clear Lake 
Research Libraries. Also the 
MacTutor source disk will contain 
only the listing published here and 
will not include any of the CLR routines used by this 
program listing, since they are obviously a commercial 
product for sale. The CLR Libraries are required to run the 
program. [We encourage you to obtain these routines (see ad 
for ordering info or watch the MacTutor mail order store for 
this product), since they greatly enhance the power of 
Microsoft Basic, which is sadly missing a majority of the 
toolbox capability. -Ed.] 

First a few comments about library routines: In 
November we discussed the process of installing BASIC 
Libraries. Please refer to that issue for information about 
installing libraries. It has come to my attention that the ID 
numbers for some desk accessories may conflict with the 
resource ID numbers for libraries even though resource ID 
numbers of different types may have the same ID according to 
Inside Macintosh. The range of ID numbers should be as 
follows: 


Range 


-32767 through -16385 
-16384 through -1 


Randomized 
Quit 


Description 


Reserved; do not use 
Used for system 
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eee ARAA an as 


Dave Kelly 


General Dynamics 
MacTutor Editorial Board 


eee 
pass 


Last item selected was 


DEORUM 
eseses 
etete 
etete 


Capablanca 


eSeses 
Oot ete 
e,e.8 
HOME 
HEME 
fot. 
ede. ? 
$,9, *| 
"MEM 


Cee ee A AAT 


AAAS IIASA IR BATA aa e, m aa a ACA B Aaea ATA 


Fig. 1 


Basic Scrolls Windows! 
resources owned by other 
system resources (see IM) 

Used for other system 
resources 
Available for your use in 
whatever way you wish 


0 through 127 


128 through 32767 


Resource ID numbers for desk accessories should be 
between 12 and 31 inclusive. Therefore, it is advisable that 
the ID numbers for libraries be assigned to numbers 128 
through 32767. In addition, the CLR Libraries have been 
assigned resource ID numbers of 10000 thru about 12000 with 
a few exceptions. You can be sure not to have ID numbers 
that don't conflict with the CLR Libraries if you use ID 20000 
through 32767 for your own libraries. This applies to the 
_Eject routine that appeared in the November issue. I 
recommend that the resource ID number for the libraries be 
changed as explained above. The _Eject routine works fine in 
most cases, but there is a chance that the ID number will 
conflict with something else. 

Please be aware of how to define variables for use in your 
libraries. For some reason Integer variables used in Libraries 
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routines should be defined with a % (following the variable 
name) instead of using the DEFINT statement. I tried the 
statement, DEFINT a-z to define integers throughout the 
entire program and when a library routine 1s executed an error 
results. You may use DEFINT as long as the name of the 
variables used appear later in alphabetical order than the 
variables defined in the DEFINT statement. I saw no 
difference between BASIC 2.0 and BASIC 2.1 as far as this 
problem is concerned. 

The demo program demonstrates the use of the CLR 
Libraries for implementing scroll bars within your BASIC 
programs. The standard Macintosh scroll bar is a predefined 
type of dial accessed through the Control Manager. The CLR 
Libraries manual (for CLR ToolLib) describes the functions 
which are provided for using the scroll bar to scroll text stored 
in an array of string variables. In summary they are: 


CLR Routine Purpose 

ActiveScroll: Scroll bar is made active 

DisposeScroll: Scroll bar is disposed and memory 
is released 

HideScroll: Scroll bar is made invisible 

InactiveScroll: Scroll bar is made inactive 

MoveScroll: Moves a scroll bar 

NewScroll: Create a new scroll bar 

ScrollText: Scroll text in an array of string 


variables 

Get value of current scroll box. 
Set value of current scroll box. 
Make scroll bar visible 

Set the size of the scroll bar. 


GetScrollValue: 
SetScrollValue: 
ShowScroll: 
SizeScroll: 


The first thing to do in creating your own scroll bars is to 
determine what you want to scroll. Set up an array of string 
variables ( in the program the string is named text$ ). Next, 
decide size and location of the rectangle where the scrolling 
should take place. The array TextRect% stores the rectangle 
location of the area where the text will scroll. The array 
ScrollText% stores the rectangle indicating the size and 
location of the scroll bar itself. The scroll bar may be resized 
with the SizeScroll command if necessary. A handy routine, 
SetRect, is used to set up the rectangles. This saves you from 
having to set each variable of the rectangle array one at a time. 
You simply type SetRect statement, the rectangle array to 
define and then the (X1,Y 1)-(X2-Y2) coordinates. Example: 


SetRect ScrollRect%(1), 151,30,167,250 


where X12151,Y 1230, X2=167, Y2=250. Be sure to initialize 
any variables to be used in a library routine by setting the 
variable equal to zero or some other number. This reserves the 
variable space so that the library routine can find it when it is 
used by the routine. Also don't forget to define all of your 
array variables with DIM statements. 

Scroll bars must be initially defined using the statement 
NewScroll. NewScroll creates a scroll bar and returns a 
handle. Many of the CLR Libraries use handles to point to a 
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location in memory. In this case, the scroll bar handle points 
to the scroll bar to be used by the statements that follow. 
Don't try to print or restore a handle as the handle variable is 
not in a standard MSBASIC format. In the NewScroll 
statement you tell the routine what variable name you want to 
call the handle, in the program the handle is ScrollBar. The 
handle name is followed by the scroll rectangle array, then by 
a parameter indicating if the scrollbar will be visible 
(1zvisible, O-invisible)J. You may later hide or show the 
scroll bar with the HideScroll or ShowScroll statements. The 
next parameters in the NewScroll statement is the minimum 
value for the scroll bar indicator followed by the maximum 
value for the scroll bar indicator and then followed by the 
initial starting value of the scrollbar. Just think of the scroll 
box as a pointer in which the one end of the scroll bar is the 
minimum value and the other end is the maximum value. 

The ScrollText statement is used to set the position of the 
scroll box. The Loop: routine in the program loops through 
the ScrollText statement with different values of the 
LineNum% and Top% (see program). Top% is used as an 
index of the line to appear at the top of the scrolled rectangle. 
If Top%=0 then the scroll bar will be redrawn. The value of 
LineNum% indicates the line of text which should be 
highlighted. When Top%=0 the scroll bar and text is redrawn 
and the indicated line will be highlighted. LineNum%=0 when 
no text is to be highlighted. 

The MouseDown: routine determines if the mouse has 
been pressed inside the text rectangle. If it is then the line 
number, LineNum%, is calculated. The routine SetPt sets the 
Pt%(1)  MOUSE(Q) and Pt%(2) = MOUSE(1). PtünRect 
determines if the point Pt% is in the text rectangle. The 
remainder of the MouseDown routine calculates the 
linenumber to be highlighted. 

In your own program, it is the program's responsibility to 
determine which line of text was clicked. The Scroll Demo 
program will select the line of text pointed to when the cursor 
is selected. More possibilities could be worked out by 
determining when the mouse is dragged across the text 
rectangle. Also you should be aware of the size and style of 
the font being displayed in the text rectangle. The number of 
pixels ScrollText spaces down between lines of text is equal to 
the existing font's height«descent-4. The height and descent 
can be obtained with the GetFontInfo statement (another CLR 
routine). Text is always printed within the rectangle passed to 
the ScrollText routine. If you wish to have a border around 
the text rectangle, you will have to draw it yourself. The 
BASIC statement LINE is used in the demo program to draw 
a border around the text. If the window containing the scroll 
bar needs refreshing, the text and scroll bar will automatically 
be refreshed when the ScrollText statement is issued (with 
Top%=0 and ScrollText is issued, the text is redrawn). The 
border (if any) will not be automatically drawn. You should 
refresh the border as you would any other window needing 
refreshing. 

To close out the scroll bar, use DisposeScroll. If your 
program terminates prematurely because of syntax error or by 
typing command-".", then you should type DisposeScroll 
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ScrollBar, where ScrollBar is the handle to the ScrollBar. If 
you forget to dispose the scrollbar and forget the scrollbar 
handle the scrollbar will not go away without quitting BASIC. 
Also the memory required for the scrollbar will still be 
reserved and cannot be reclaimed till the scrollbar is disposed 
of. 

Some other routines used in the program: 


SortString: Sorts a string array alphabetically 
Shuffle: Randumizes a string array. 
ChangeCursor: Set the cursor to a cursor in the 


System resource file. 


The usefullness of these routines and other CLR routines 
will be left to future articles. 


‘Scroll Demo 

‘By Dave Kelly & Clear Lake Research 
"@MACTUTOR 1985 

"REQUIRES CLR LIBRARIES 


This program illustrates the use of the scroll bar 
as well as a few other statements from 
CLR ToolLib and CLR MathStatLib. 
The names of 15 famous chessplayers are presented 
on the screen and can be scrolled with the scroll bar. 
The arrows as well as the scroll box are functional. 
A selected name will be highlighted. 
The order of the names can be alphabetized or randomized. 
When the "OK button" is pressed the selected name is 
printed. 


LIBRARY" ToolLib" 
LIBRARY"MathStatL ib" 
OPTION BASE ! 
DIM TextRect£(4)5,ScrollRect£$(4), text$C 15) 
DIM Pt%(2), Index$C 15), Temp$C 15) 
Initialize: 
Scrol1Barz 
Top$-0 
inRect%=0 
L ineNum%=0 
WINDOW 1, , (68, 48)-(250,338),2 
WINDOW 2, , (280, 100)- (500, 200),2 
TEXTFONT(2) 
LOCATE 2,9:PRINT "Professor Mac's" 
LOCATE ,9:PRINT "Scroll Bar Demo" 
TEXTFONT(3) : TEXTSIZEC9) 
LOCATE ,2:PRINT "Select your favorite World Chess 
Champion." 
TEXTSIZEC 12) : TEXTFONT) 
WINDOW 1 
SetRect TextRect%( 1), 20,30, 151,250 
SetRect ScrollRect$C12, 151,30, 167,250 
FOR i= 1 TO 15 
Index&C i =i 


i 
BUTTON 1,1, "0K", (55, 268)-( 125,280) 
FOR i= 1 TO 15 

READ text$Ci) 


2, 1, "Randomized" 
3 "Quit" 
menu bar 


H OD a mea ma pa = 


e 
— 
@ 
o 
3 
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ce 

SE — Lag a n n 
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CreateScrol]: 
LINE (20,30)-C151,249), ,b 
NewScroll ScrollBar,ScrollRect£C 12, 1, 1, 10, 1 
' visible with values ranging from 1-10 startring at 1 
' these parameters are reset by a subsequent 
' ScrollText statement 


Loop: 
ScrollText ScrollBar,TextRect$C 12, text$C 12, Top$, 15, LineNumS 
IF MOUSECO? Ø THEN GOSUB MouseDown 
d$-DIALOG(C? ) 
IF d$-1 THEN GOSUB Buttonselected 
IF d%= 5 THEN GOSUB Update 
IF MENUCO? Ó Ø THEN GOSUB MenuEvent 
GOTO Loop 


Buttonselected: 
WINDOW OUTPUT 2 
as 


TEXTFONT (0) 

LOCATE 2,4 

PRINT "Last item selected was" 

LOCATE 4, 10 

IF LineNum$-0 THEN PRINT "Nothing" ELSE PRINT 
tex t$(LineNums) 

TEXTFONT( 1) 

WINDOW OUTPUT 1 

LineNum%=8:GOSUB Update 


Finish: 
DisposeScroll ScrollBar 
BUTTON CLOSE 1 
WINDOW CLOSE 2 
WINDOW 1,"Scrol! Demo", (2,402- (510,290), 1 
aS 
END 


Update: 
Top$-0 
That's all that's required since ScrollText will redraw the 


ext. 
LINE (20,30)-(151,249), ,b 
RETURN 


MouseDown: 
SetPt Pt2C15, MOUSEC 1), MOUSE(2) 
PtInRect Pt%( 1), TextRect$C 12, inRect£ 
' Is mousedown in TextRect? 
IF NOT inRect% THEN MouseOver 
' IF @¢= Pt$C D - TextRect%(1) <= 19 then 
LineNum$-TopS 
' IF 20¢= Pt$CD - TextRect$C1) <= 39 then 
" LineNum$-Top$*1 etc. 
' The following is a fast method of calculating 
L ineNum$ 
LineNum®=(Pt%( 1)-TextRect&¢ 122A20* Top$ 
- Make ScrollText redraw text with LineNum& selected 
Top%=0 
ScrollText ScrollBar,TextRect$C 12, text$C 12, Top$, 15, LineNum$ 


MouseOver : 
WHILE MOUSECO) € 0: END 
‘wait for mouse button to come up 


MenuEvent : 
ChangeCursor 4 ‘make cursor the watch 
ON MENUC1) GOSUB SortIt,ScrembleIt,Finish 
MENU 


Top%=8 
INI TCURSOR 


‘so it will be redrawn 


SortIt: 
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SortString 15, text$C 1) 
LineNum%=0 


ScrambleIt: 
Shuffle 15,Index$(1) ‘scramble the indexes 
LineNum$-0 
FOR i= 1 TO 15 
Temp$Ciostext$Cio 
i 


FOR i= 1 TO 15 
text$Ci)-Temp$CIndex&Ci)) 
i 


RETURN 

DATA Morphy, Anderssen, Steinitz,Lasker , Capablanca 
DATA Alekhine, Euwe, Botvinnik, Smyslov, Tal,Petrosian 
DATA Spassky, Fischer , Karpov, Kasparov 


Questions and Answers 


Thank you to those who have sent in suggestions or 
questions that they may have concerning this column. 
MacTutor will continue to try to provide the information that 
you are hungry for. In response to letters received, here are 
the following questions/suggestions and answers: 

Q. How do you tell your program to quit to the finder, 
instead of BASIC? 

A. The command SYSTEM terminates the program and 
goes to the finder. 


Q. A call to a sort routine is badly needed. 

A. A quicksort program was printed in the Sept. 
MacTutor (Ask Prof. Mac column). CLR MathStat Library 
has various sort routines available. [Basic Smoke is also 
marketing both bubble and shell sort routines, string sorts 
with tags in assembly. Contact Jim Shores, 139 Alpine Dr., 
Closter, NJ 07624. Price is just $4 for each sort routine 
(these are in assembly for Basic). -Ed. ] 

Q. Calls to clear parts of the screen would be helpful. 

A. One way to clear a part of the screen is to use the 
GET and PUT statement to clear a section of the screen. Use 
PUT to read in a blank section of the desired size, then use 
GET to write it back whenever it is needed. Another way 
might be to open a window over the section to clear and then 
close it again without refreshing the screen. 

Q. How can the defaults for the TAB function be changed 
while editing? As it is, one might as well use the space bar. 

A. I don't know of any way to change the TAB fields. 


Please continue to send in your suggestions or questions. 
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Basic School 


Asm Utility Speeds Screen Blanking 


For those that remember Professor Mac's Screen Pokes 
presented in the April 1985 issue of MacTutor, we discussed 
the Macintosh screen and how to poke the screen to all blank. 
The method presented there was very slow. Until such time as 
someone comes out with a MS BASIC compiler most 
routines will be slow. MacTutor now has a call out to anyone 
that has a complier for MS BASIC to step forward and become 
famous. Please contact us if you have any information to 
give us about compiled BASIC. 

This month we will provide the alternative screen poke 
method using a library written in 68000 code. These routines 
were designed to work with the 512K or 128K versions of the 
Macintosh, however, the code may be modified to be used 
with other memory sizes. 

If you are unfamiliar with BASIC libraries then we 
recommend that you refer to the BASIC School article in the 
November 1985 MacTutor on Building a Machine Language 
Library routine. (Back issues are available). The listings that 
follow are assembled in the same manner as discussed in that 
column. 

There are three code routines that you need to be concerned 
with. The LIBinit.asm (Listing 1) routine may be found on 
page 44 of the Nov. 85 MacTutor. The second routine stores 
$FFFFFFFF in all screen locations, thus blacking out the 
entire screen. The third routine inverts all of the screen 
locations. We thank Serge Rostan of Pontoise, France for 
contributing the main code for the invert routine. [If you have 
some good ideas on Basic, please write Dave care of MacTutor 
and see them in print. -Ed] 

The BlankScreen routine (Listing 2) is accessed by the 
statement: CALL BlankScreen (memory%) where memory% 
is the memory of your particular system (i. e. use 
memory%=512 or memory%=128). This routine works fine 
for 512K or 128K Macs, but you will have to change the 
equates for Screen512 and/or Screen128 (see listing 2) in order 
to accomodate other memory sizes. The equates 
'GetNextLibArg', 'IntegerArg' and 'BasicError' are BASIC 
routines defined in BMLL (Microsoft's Building Machine 
Language Libraries) which library routines may call. The 
BlankScreen routine reads the memory% parameter and 
determines the screen location. Then each location is loaded 
with $FFFFFFFF and the screen is blank. The routine then 
returns back to the calling program. 

The InvertScreen routine (Listing 3) works much the same 
as the BlankScreen routine. You may call the routine with the 
statement: CALL InvertScreen (memory%). The passed 
integer variable memory% is the same as in the BlankScreen 
routine. The only difference in this routine is that each 
memory location is exclusive-ored with the value 
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$FFFFFFFF. 

Listing 4 and 5 are the Linker and Resource complier files 
needed by the MDS system to create the library resource file. 
See Nov 1985 MacTutor for details on how to us these files. 

The Screen Demo program in listing 6 demonstrates the 
use of the BlankScreen and InvertScreen routines. It is 
advisable but not mandatory that you hide the cursor using 
HIDECURSOR before blanking or inverting the screen. 
The cursor may be turned on again with the 
SHOWCURSOR statement. If the cursor is not disabled 
then the 16 X 16 cursor location will not be blanked or 
inverted properly. These libraries may be used to create 
special effects in your program such as flashing the screen. 

Expanding BASIC using library routines greatly improves 
the capabilities of your programs. If you have a favorite 
library routine, please send it to us. We would like to share 
more libraries with other useful purposes. 

LISTING 1 


,LIBinit routine (See MacTutor Nov. 1985 pg. 44 for comments) 
,Save as LIBinit.asm 


LIBVER. Result EQU 6 
LIBinit: 

CLR.W LIBVER_Result(a@) 
LIBinitExit: 

MOVEQ "tg, d 


puce. Vo re i e erae or eom 
LISTING 2 


; BASIC BlankScreen Library Source Code 
» By Dave Kelly 
; MacTutor 1985 


; Synopsis: 
; CALL BlankScreen (memory%) 
;Output: 
GetNextLibArg EQU $2A 
IntegerArg EQU $32 
BasicError EQU $42 
Screend 12 EQU ((512- 128 )* 1024 )* 108288 
Screen 128 EQU 198288 
JSR GetNextL ibArg(a5) ;Get the next argument 
JSR IntegerArg(a5) — ;[d3:w] = integer error if erg 
,can't be forced into an 
j integer. 
CMP .W #128 ,d3 
BEQ Do 128 jbranch if 128K memory 
CMP .W #512,d3 
BEQ Do5 12 ,branch if 512K memory 
Device Unavailable: 
MOVEQ 868 , d2 ;Device Unavailable error 
JSR BasicError(a5) 
DoS 12: 
LEA Screend 12, Ad 
BRA Blank 
Do128: 
LEA Screen 128, A0 
Blank: 
MOVE .W 85472-1,d1 ,Setup high screen address 
MOVE.L “$FFFFFFFF, d ,nove to dø 
Loop: 
MOVE.L dð, CAG )+ ,Set screen address to dð 
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DBRA di,Loop ScreenLib CODE 3 


RTS LISTING 6 
GetIntegerVar: ‘Screen Demo 
JSR GetNextLibArg(a5) ;Get the next argument ‘By Dave Kelly 
JSR IntegerArg(a5)  ;[d3:w] = integer error if arg 'eMacTutor 1986 
;can't be forced into an LIBRARY "Screen Demo" 
j integer mem%= 128: IF FRECO)> 75000! THEN mem%=5 12 


GOSUB Setmenubar 
LISTING 3 MENU ON 
; BASIC InvertScreen Library Source Code ON MENU GOSUB menucheck 
; By Dave Kelly loop: GOTO loop 
; MacTutor 1985 menucheck : 
save InvertScreen.asm menunumber=MENUC@): IF menunumber«»6 THEN RETURN 


; Synopsis: menui tem=MENUC 1) : MENU 
; CALL InvertScreen C memory%) ON menuitem GOSUB Blank, invert,Flash,Demo,Quit 
Output: Setnenubar : 
GetNextLibArg EQU $2A MENU RESET ' Re-do menu bar 
IntegerArg EQ — $32 MENU 6,0, 1, "Program Menu" 
BasicError EQU $42 MENU 6, 1, 1, "Blank Screen" 
Screend 12 EQU €C5 12- 128 )* 1824 )+ 108288 MENU 6,2,1,"Invert Screen" 
Screen 128 EQU 108288 MENU 6,3, 1, "Flesh Screen" 
BSR GetIntegerVer j integer arg in [d3:w] MCNU 6,4, 1, "Demo" 
CMP .W #128 ,d3 MENU 6,5, 1, "Quit" 
BEQ Do128 ;brench if 128K memory RETURN 
CMP .W $512,d3 Blank: 
BEQ Do5 12 ;brench if 512K memory HIDECURSOR 
Device-Uneveilable: CALL BlankScreen(mem$) 
MOVEQ #68 , d2 ;Device Unavailable error SHOW 
JSR BasicError(a5d) RETURN 
Dod 12: invert: 
LEA Screen5 12, A0 HIDECURSOR 
BRA Invert CALL inver tScreen(memS) 
Do 128: SHOWCURSOR 
LEA Screen 128, A0 RETURN 
Invert: Flesh: 
MOVE .W #5472-1,D1 HIDECURSOR 
MOVE.L #$FFFFFFFF,DØ FOR i=Ø TO 100 
Loop: CALL invertScreenCmem$) 
EOR.L DØ, CA22* NEXT 
DBRA D1,Loop SHOWCURSOR 
RTS RETURN 
GetIntegerVar: Demo: 
JSR GetNextLibArg(a5) ;Get the next argument WINDOW CLOSE 1 
JSR IntegerArg(a5)  ;[d3:w] = integer Cerror if GOSUB Blank 
arg WINDOW 1,"",C(42,902-(475,300),3 
can't be forced into an PRINT "Click here" 
j integer WHILE MOUSECO) O 1: VEND 
GOSUB invert 
| LISTING 4 WHILE MOUSECO) O> 1: WEND 
Screen Library Link GOSUB invert:CLS:GOSUB invert 
,MacTutor 1986 WINDOW 2,"",C102, 140)-C410,240),3 
PRINT "Click here" 
/OUTPUT ScreenLib WHILE MOUSE(@)<> 1: WEND 
LIBinit.Rel GOSUB invert 
< WHILE MOUSEC2O) €» 1: WEND 
InvertScreen.Rel GOSUB invert:CLS:GOSUB invert 
( WINDOW 3,"",(152, 165)-(368,215),3 
BlankScreen. Rel PRINT "Click here" 
WHILE MOUSECOD O 1: WEND 
GOSUB invert 
LISTING 5 WHILE MOUSE(@)<> 1: WEND 
ScreenLib.Rsrc GOSUB invert:(LS:GOSUB invert 
BLIB GOSUB invert 
TYPE CODE = GNRL PRINT SPC(4);"Please make selection”: PRINT SPC(5); "from 
ee menus above!" 
ScreenLib CODE 1 Quit: 
FOR i=1 TO 4 
TYPE CODE = GNRL WINDOW CLOSE i 
InvertScreen,2 NEXT i 
R MENU RESET:LIBRARY CLOSE 
ScreenLib CODE 2 CLS: END 
TYPE CODE = GNRL Cod! 


BlankScreen,3 
R 


(eener = N 
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Special Projects 
Subprograms in Basic Explained 


Versatile Input Routine 


So, you are writing a program in Microsoft BASIC and 
the user of the program has to supply information for the 
program to process. The tradtional, and — before Microsoft 
BASIC for the Macintosh — sometimes the only available, 
way for a BASIC program to obtain data from the keyboard is 
via the INPUT statement. This yeoman method has worked 
for many years and has proven its worth. It also has shown 
all its faults. In some varieties of BASIC, certain characters 
(notably the comma and colon) cannot be read by INPUT. 
Unless you incorporate error checking routines (which can 
require extensive programming), the only way the user can 
correct errors is for him to notice the error before he presses 
Return so that he can backspace and retype his data. Error 
checking routines range from a simple 


INPUT "Do you want to make any changes? (Y/N) "; YN$ 


followed by more questions and INPUT statements, to 
complex screen structures with vertical and horizontal tabbing 
combined with the INPUT statement. 

If the program uses formatted displays, then more 
programming effort may be required to reformat the screen for 
the display after each INPUT sequence. 

Microsoft BASIC for the Macintosh (Version 2.0 or 
later) has some built-in features that can help you alleviate 
some, if not all, of these problems. Formatted screen displays 
can be kept intact by overlaying windows for the input 
routines. INPUT can be replaced by EDIT FIELD and EDIT$ 
to provide a powerful error-checking routine that allows the 
operator to check all of his data before signifying that 
everything is correct and proceeding to the next task. 

Listing 1 contains a routine just for this purpose. The 
routine is in the form of a subprogram so that it can be 
inserted anywhere in your program. Sub- programs are, to my 
knowledge, unique to the Macintosh version of BASIC. They 
are independent modules that can be anywhere within a 
program listing and are completely ignored by BASIC unless 
they are CALLed by the program. All variables used by a 
subprogram remain with the subprogram and do not affect the 
variables in the main program unless explicitly allowed to do 
so by the program. If A = 10 in the main program and a 
subprogam sets A equal to 136.43, when the subprogram 
exited, A would still equal 10 in the main program. Pascal 
programmers will recognize subprograms as being very 
similar to Pascal's procedures. 

The listing has two parts. The first is an example of a 
main program for the subprogram to work within. The second 
is the the subprogram itself. 
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EN 


The main program starts by setting all variables as 
integers. It then DIMensions the arrays label$, info$, and 
corner. Label$ contains the names of the edit fields; info$ 
holds the actual information inputted, and corner defines the 
four corners of the main window. Next, the label$ and corner 
data are read into their respective arrays and some sample text 
is printed in the window. The program then CALLs the 
subprogram, which is named inputroutine. (Note that the 
keyword "CALL" is optional) After the subprogram is 
exited, the main program transfers the data from the general 
array to individually named variables. It then formats and 
prints the data and asks whether the user wants to redo the 
operation and then waits for a key press to end or redo the 
program. 

Look at the line “doitagain” in the main program. This 
line calls the subroutine. The list following the subprogram's 
name contains those variables that are passed to the 
subprogram. If a variable is not in this list, it is not passed to 
the subprogram. Corner, info$ and label$ each has a pair of 
parentheses after it. This is to tell BASIC that these elements 
are array variables. 

In addition to passing variables, you can also pass 
expressions. As an example, if you need to pass the area of a 
circle to a subprogram called computeit, but computit does not 
need to know the radius, you can pass the area like this: 


CALL computit (3.14159 * radius ^ 2) 


Subprograms cannot change the values of expressions 
passed to it; they can change only the values of variables. If 
you need to pass a variable and want to make sure that the 
subprogram will not change its value, place parentheses 
around the variable and it will be passed as a value by 
expression. 

Now let's look at the subprogram itself. The first line 
starts with SUB to indicate that it is a subprogram. The next 
part of the line is the subprogram's name, followed by a 
variable list in parentheses. The line concludes with the 
keyword STATIC. 

The subprogram next defines the sizes of window 2 and 
the portion of window 1 that will be hidden by window 2. It 
continues by dimensioning the rectangle array that will hold 
the screen behind window 2; then it defines the shape of the 
text cursor. The next line, which starts with the kety word 
GET, stores the about to be covered portion of window 1 in 
the previously dimensioned rectangle array. Window 2 is then 
opened, covering a portion of window 1. 

Then the subprogram goes to the subroutine "refresh." 
This routine clears the window, sets the font to 0 (Chicago), 
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and prints the labels for the edit fields. It then returns to the 
main part of the sub program. This subroutine is accessed 
whenever a portion of the window is covered by another 
window such as the command or a list window. 

The subprogram then resets the font to the default font 
(Geneva) and draws the edit fields and an OK button. When 
the edit fields are drawn, the latest information generated in 
" é File Edit Search Run Windows 3 

This is the background window in which the main program runs. 
t 


First Name 


Street and No. 


234 mein Street 


ST 
Phone 
(602) 458-1234 


those fields are placed into them for editing. This helps when 
a field remains the same from one record to another. Because 
the text in each field is selected when the field is first chosen 
by tabbing to it, putting in new data is not any more difficult 
than if the field were left blank.. 

The next line flushes any dialog actions from memory 
and then allows the program to continue by initializing and 
entering a WHILE loop. The first block of programming 
within the loop monitors the cursor position on the screen and 
whenever the cursor moves into an edit field, changes it to an I- 
beam to show text insertion. When the cursor moves outside 
of the edit field, it reverts to the default arrow. If you have 
fewer than 10 edit fields, you will need to make minor 
modifications to this portion of the program. 

The next block looks for dialog actions. The only dialog 
events it recognizes are clicking in the OK box or in an edit 
field, pressing the Return or Tab key, or obscuring the 
window with another window. 

If the window is obscured, the program goes to the 
refresh subroutine which clears the window and reprints the 
field labels. Neither the CLS statement nor covering the 
window affect buttons or edit fields (including their contents), 
so they do not need to be refreshed. 

If the dialgog event shows that the Tab key had been 
pressed or that the mouse was clicked in an edit field, the 
program goes to the tabfield subroutine. If the Tab key had 
been pressed, the routine increments or decrements the current 
edit field by 1. Note the line “shiftkey = (PEEK (379) and 
&H1) * 2.” Peeking memory location 379 monitors various 
keys on the keyboard. If bit 0 is set, that means that the shift 
key has been pressed. By ANDing location 379 with the 
value 1, the result is 1 if the shift key has been pressed and is 
0 if it has not been pressed. If the TAB key has been pressed, 
rather than the mouse clicked in the and edit field, the next line 
subtracts the value shiftkey (which is either 2 or O) from the 
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value of currentfield + 1. Therefore the value of currentfield is 
increased by 1 if the TAB key has been pressed and the shift 
key has not been pressed. But, if both the shift and TAB keys 
have been pressed, then currentfield is decreased by 1. This 
allows for reverse tabbing. If the value of currentfield is less 
than 1 or greater than maxfields, the value is then currentfield 
is set to maxfields or 1, respectively. If the TAB key had not 
been pressed, that means that the subroutine was entered 
because an edit field was selected by a mouse click, and the 
current field is set to that field. The subroutine then returns to 
the line that called it. 

If Retum (or Enter) is pressed or the OK button is 
clicked, the variable dialogactive is set to false (0) and the 
WHILE loop ends. 

Note that at no time an express INPUT is made to obtain 
data from the computer operator. All the operator has to do is 
enter the information in the edit field boxes in any order of his 
choice. When the WHILE loop is exited by pressing Return 
or clicking in the OK button, the information stored in the 
variable array EDIT$Q are transferred to the info$() variable 
array. Note that this transfer of data must be done before 
window 2 is closed. When the window closes, the 
information in the edit fields and EDIT$ will be lost. Note 
that EDIT$ is never explicitly DIMensioned; DIMensioning is 
automatically done as the edit fields are created. 

Before the subprogram exits and returns to the main 
program, it closes window 2; PUTS the stored screen data 
back, thereby restoring window 1; and ERASEs the cursor and 
rect arrays. Erasing the arrays serves two purposes: 


l. It enables them to be reinitialized when the 
subprogram is next called and 

2. It frees the memory used by these arrays so the 
program can use it for other purposes. 


The sub program does seem at first glance to be a bit 
complex and involved to be a substitute for a series of simple 
INPUT statements. However, if you were to write an input 
routine to get a set of data and allow complete editing and error 
checking of that data, it would be more involved than this 
routine. This subprogam can be simplified if size and 
memory are a consideration. The first simplification is be to 
eliminate the block of programming that changes the shape of 
the cursor. This block starts with the line “dummy = 
MOUSE (0)" and ends with the line that ends "ELSE 
INITCURSOR." You can then delete all lines that refer to 
or define the cursor array. The second deletion is the 
subroutine “tabfield.” If you do that, you must also delete the 
line that starts "IF status = 2" since this line calls the 
subroutine. If you delete this routine, the operator can move 
between edit fields only by means of the mouse. Pressing the 
Tab key would no longer change the edit fields. 


HOW TO USE THE PROGRAM 


After you enter the entire program and try it out, delete 
the main program and keep only the subprogram. Save the 
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subprogram, choosing the TEXT option in the save window. 
When you are ready to use it, MERGE it into your program. 
MERGE works only if the merged program has been saved in 
TEXT format. 

Prior to calling the subprogram, your program must set 
the variable “‘maxfields” to the number of fields to be input; 
the number of edit fields and labels are taken from this 
number. You need then only put in the names of the labels 
(in the label$ array) and transfer the information from the 
info$ array to your specific variables. The only other change 
you must make is to the cursor shape-changing routine if you 
haven't deleted it and if maxfields is other than 10. You can 
call the subprogram from different parts of your program, 
using appropriate values for maxfields and labels. 

Using this subprogram in your programs will give you a 
clean-looking, efficient, error-free input routine and save you 
programming time. 

Program Listing 


DEFINT a-z 
maxfields = 10 'number of fields to be inputted 


e B ped t $m axfields), info$ (maxfields), corner (4) 
ame First Name,MI,Title,Street and 
ers Ci iy ST, ZIP Phone Ref st: ‘field labels 
FOR i = 1 TO maxfields: READ label$(i): NEXT 


‘Create main window 


DATA s 39. oo 310: ‘Change Jg uii to re-size windows 
FOR i = 1 TO 4: READ corner (i): NEXT 
WINDOW E "(corner (1),corner (2))-(corner (3),corner (4)),2 


PRINT ned s the background window in which 
the main program runs." 

PRINT “ity will be covered by the data input 
window and restored when” 

PRINT "the data input window is closed." 


doitagain: inputroutine corner (), maxfields, label$(), info$() 


Lname$ = info$(1): omama iy info$(2) 
MI$ = nios s (S eS. 4 

street$ = VIS = in ae 

ST$ = info$(7) :Z RE info$ 

Phone$ = info$(9): EFNUN i = info$(10) 


‘Use VAL function to change strings to numbers where necessary 


PRINT 
LER TA <>™ Ly PRINT Pre$;" "; 
IF MI$ on * THÉN PRINT MI$;". "; 
PRINT Lname$ 
F street$ <> "" THEN PANT — 
IF City$ <> "" THEN PRIN /$; * " 
IF ST$ <> "" THEN P PRINT: Si * Zips 
IF de <> "" THEN PRINT Phone$ 
IF REFNUMS <> "" THEN PRINT label$(10);" ":REFNUM$ 
PRINT: PRINT"Press Return to end or press any other key to try it 
again." 


loop: e = INKEYS: IF test$ = "" THEN loop 
E IF test$ - CHR$(13) THEN END 
ELSE doitagain 


‘Subroutine begins here 


SUB M SO STA (corner(), maxfields, label$(), 
info$ 
left = 25: top = 50: right = 480: bottom = 300 ‘window 2 corners; change 
to re-size window 
getleft = left - comer (1) -1: gettop = top - corner (2) 
"E getright = right - comers fe etbottom = 
bottom - corner (2) ‘corners o p le for GET 
DIM rect(4+(((g getbottom-gettop)+ pen 
(((getright-getleft) + IT )), HAE. (33) 
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‘Create l-beam cursor 
FOR i = 3 TO 12: cursor (i) = T is NEXT 


cursor (0) = &H630: cursor = cursor 1 
cursor (1) = &H140: cursor = cursor 
cursor (2) = &H80: cursor 13) cursor sor (2) 
FOR i = 16 TO HG cursor (i) = &HO: 

cursor 

ctor 133 = SHS 


GET(getleft,gettop)-(getright,getbottom),rect 'Preserve background 


WINDOW 2,"" (left,top)-(right,bottom),3 
bh (left,top)-(rig ) 


GOSUB refresh ‘Window refresh routine 
TEXTFONT 1 ‘setup edit fields with Geneva font 


FOR i = maxfields TO 1 STEP -1 


EDIT FIELD i infoS( (30+(fi-1) MOD 2) 
*220,(i+(i MOD 2n 20-1 Seat ) MOD 
2)*220,15«(i«(i bb ay AT 


NEXT 
BUTTON 1,1,"OK",(10,230)-(445,250) 
WHILE DIALOG (0) <> 0: WEND ‘flushes dialog queue 
dialogactive = -1 
WHILE dialogactive 
‘monitor cursor ‘Orr and switch cursor sh 


IF NO ((hloc > 30 A D hloc «220) O 


e 
dummy = MOUSE (0): hloc = MOUSE (1 d = MOUSE (2) 


> 250 AND hioc «470)) THEN INITCURSOR 


IF (hloc>30 AND eL On (hloc>250 
AND oe THEN IF (vioc>21 AND 
vloc«38) OR (vloc»61 AND vloc«78) OR 
vioc>1 y AND vloc<119) OR APH 

ND sa e NT vloc»18 
IH N SE CURSOR VARPTR 
(cursor (0)) ELSE INITCURSOR 


status = DIALOG (0) 


IF status =1 OR aes 6 THEN dialogactive = 0 'check for OK 


button or RETURN key 
IF status =2 OR status = 7 THEN GOSUB 
tabfield 'Check for click in edit field or for TAB 


ke 
IF états z 5 THEN GOSUB refresh 
WEND 


FOR i = 1 TO maxfields: info$(i) = EDIT$(i): NEXT 


WINDOW CLOSE 2 
ERA ERASE rect ,gettop),rect ‘restore backgrnd 
icm cursor 


tabfield: 'selects edit field with TAB ke 2 mouse 
shiftkey = (PEEK (379) AND &H1) * 2 


IF status = 7 THEN currentfield = currentfield +1 
- shiftkey ELSE currentfield = DIALOG(2 

IF currentfield < 1 THEN currentfield = maxfields 

IF currentfield > maxfields THEN currentfield=1 


EDIT FIELD currentfield 
RETURN 


refresh: 'redraw window contents 
CALL TEXTFONT a 
FOR i = 1 TO maxfie 
MOVETO E 1) Mop 2)*220, 


Ba MOD a 
xr label E 


RETURN 
END SUB 


Basic School 
Basic Does Regions (with CLR!) 


Hello! This month we will explore the Macintosh 
Quickdraw routines with a trip into the world of regions. This 
may be a review for some of you that program in other 
languages such as Pascal or C as this subject has been covered 
quite well in past issues of MacTutor (See Vol. 1 No. 3 
"Quickdraw does Regions” or Vol 1 No. 4 "Ports O' Call in 
Quickdraw"). Until recently it has been impossible to 
meaningfully talk about regions from MSBASIC. Wth the 
Clear Lake Research (CLR) Libraries available it is now 
possible to give BASIC equal time with the other languages 
when referring to Quickdraw. Quickdraw routines are called 
from BASIC in much the same method used in Pascal or other 
languages. In fact, we recommend that you review the Pascal 
columns referred to above as they have information which may 
pertain to any language, not just Pascal. The same is true for 
this column when discussing calls to Quickdraw or other 
routines used by all languages. 

First a bit of a review for those that are not familiar with 
Quickdraw regions and associated calls. We have available to 
us via the CLR Libraries [Note: These libraries are available 
from the MacTutor mail order store for $50 for both the 
libraries and the speech routines. -Ed.], over 20 statements 
involving regions. These are found listed with their functions 
on page 14 of the CLR manual or you may refer to Chapter 4 
of Macintosh™ Revealed, Volume One by Chernicoff and 
published by Hayden Press. Instead of going into a detailed 
study of Quickdraw I refer you to the previous issues of 
MacTutor mentioned above. (Back issues are available through 
the MacTutor Store). 

A few things to remember when working with Quickdraw: 
The horizontal coordinates increase from left to right and the 
vertical coordinates increase from top to bottom. You may 
want to think of a region as an area on the screen with a set of 
points inside the region and a set of points outside. A point 
in the region cannot be both inside and outside the region. It 
should also be noted that a graphic point is located to the 
Tight and 'below' its corresponding mathematical coordinate. 

The Region/Clip Demo program (note: requires CLR 
Libraries) will set up a region and by using the GetClip and 
SetClip statements (CLR) we can specify the region which 
we want the text (or graphics) to be drawn to. In this way, 
only drawing that occurs within the region will show up on 
the screen. Any drawing outside the region will not show up. 
This could be useful when you want to draw in a particular 
part of the screen without disturbing the contents of another 
part of the screen. The demo program first opens up the 
appropriate library: 

LIBRARY"ToolLib" 

Remember to include the disk volume name if necessary. 
I would advise you to use the Statement Mover program to 
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Fig. 1 Screen dump of our regions program 


move the libraries that you use over to the BASIC program 
file so they will always follow the program no matter what 
disk you put it on. 

Next we set up some of the array variables used by the 
program and associated library routines. If the variable is 
undeclared the libraries cannot work. Also be sure to 
dimension the arrays properly. For example, if the pattern%() 
array below were dimensioned to 0 instead of three, the routine 
SetRect would go ahead and try to store 4 variables, but would 
only be able to find one. The results could be unpredictable. 
Save your work before running your program in case there 
might be any misteaks (ha, ha). The SetRect command sets 
the left, top, right, and bottom coordinates of the array equal 
to the indicated values respectively. 


DIM R23), OvalR%C3), fontinfoS (3), patternt(3) 
x1$-50:912-20:x21-450:423-200 

SetRect R&(8),x1%,y1%,x2%,y2% 

SetRect pattern$(2),&HAA, &HAA, &HAA , &HAA 
SetRect pattern£C2),&HAA, &HAA, &HAA , &HAA 


The window is opened and the background is set to the 
background pattern defined in the pattern96() array. The screen 
is cleared so that the background pattern will be redrawn. The 
pattern%() array is cleared with SetRect and the background 
pattern cleared so that subsequent CLS statements will clear 
the screen to white. Note that the CLS command only clears 
within the clipping region. When a BASIC window is opened 


up the clipping region defaults to the window size. 
WINDOW 1,"",(2,30)-(508,275),4 
CALL BACKPAT CVARPTRCpattern$(2022) 
CLS 


SetRect pattern%(0),0,9,8,8 
CALL BACKPATCVARPTR(pattern%(8))) 


Another CLR Library statement allows us to determine the 
size of the currently selected font. The program sets the 
TEXTSIZE to 9 and then calls the getfontinfo routine. The 
font info is returned in the array fontinfo%(. The variable 
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fontinfo%(0) returns the ascent, fontinfo%(1) returns the 
descent, fontinfo%(2) returns the maximum character width, 
and fontinfo%(3) returns the vertical distance between the 
descent line and the ascent line below it. The program needed 
to know the total spacing for each line of text which is given 
by the sum of the ascent, descent, and the vertical distance 
between the descent line and the ascent line below it. Note 
that a call to getfontinfo would be useful for programs trying 
to determine the number of lines of text to print per page (or 
screen) when using various sizes and styles of fonts. 

CALL TEXTSIZEC9) 

getfontinfo fontinfo% (a) 

fh%=fontinfo%(O)+fontinfo&C 1) 

Next the region handle variables are defined and the 
clipping region represented by the screen is stored away so it 
may be restored again later. If the OldReg! handle were not 
saved in this way, the last clipping region would be used the 
next time printing to the window. To define a new region, 
execute a NewRgn command. This allocates space for the new 
region and the region is initialized to the empty region. 
GetClip sets the region with the handle indicated (in this case 
OldReg! is the handle) to the current clip region. 

handle! =0 

01dReg! =0 

NewRgn OldReg! 

getclip OldReg! 

We now define the region which we want to use as our 
clipping region. First we initialize the region with NewRgn 
with handle! . Next we may define the contents of the region. 
A series of graphics statements will make up the region we 
wish to create. We open the region with OpenRgn and follow 
it with whatever graphics commands we desire such as 
FRAMEOVAL, FRAMERECT, LINE, and others. Note that 
arcs cannot form part of the region definition. The end of the 
definition is indicated with the CloseRgn handle! statement 
where handle! is the handle! of the region being defined. Next 
the clipping region is set to the region with handle! with the 
statement Setclip handle! . All points either printed or drawn 
outside the region will not be shown. Only those points 
inside the region may be seen when printing is done inside the 
region. 

NewRgn handle! 

OpenRgn 

FRAMEOVAL VARPTRCRZCO)) 

CloseRgn handle! 

Setclip handle! 

The next several statements of the program print text in 
the region which has been set as the clipping region. Note 
that CLR has provided us with the Drawtext text$ statement 
to drawtext much faster than with the BASIC PRINT 
statement. To use drawtext you must move the quickdraw pen 
to the desired pixel position and issue the drawtext statement. 
It is harder to use that the BASIC printing statements but the 
speed difference makes it worth using when speed counts. 

There are other statements which may be used with 
regions. One region may be subtracted from another with 
DiffRgn or use XorRgn or UnionRgn to combine regions. 
These and other commands will be left for future MacTutor 
columns. The program uses the framergn command to draw a 
border around the edge of the region. The current pensize is 
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used for the border line. 

CALL PENSIZE (2,2) 

fremergn handle! 

Now for a word of caution: If your program should crash 
for some reason before your region is disposed of, you should 
be prepared to manually type in the disposeRgn statement and 
appropriate handle or handles for the regions used. Remember 
to dispose of all regions before quiting your program as the 
Space for the regions has been allocated and will not be 
returned unless the regions have been disposed of. Otherwise, 
you may find yourself wondering why you are running out of 
room on the heap. The statement is: 

disposergn handle! 

A few words on the CLR Libraries clipping statements: 
The CLR Libraries manual mentions a statement named 
ClipRect which is supposed to set the clipping region to a 
rectangle. The ClipRect routine is not included on my 
ToolLib file. No need to panic yet, however, because the 
same command can be reconstructed with a combination of 
region calls and clipping calls. One solution is to use the 
following sequence to do a ClipRect (set the clipping region 
to a rectangle): 

DIM rect%(3) 

handle! 

SetRect rect$(05,x1$,9u18, x2%, y2% 

NewRgn handle! 

OpenRgn 

FRAMERECT € VARPTR(Rect$C0)) 

CloseRgn handle! 

Setclip handle! 

You may also use SetRectRgn or RectRgn to set a region 
equal to a rectangle. The statement syntax is: 

SetRectRgn hand! , lef t%, top% right% bottom’ 

The region with handle hand! is set equal to the rectangle 
with coordinates left%,top%,right%, and bottom%. 

RectRgn hand!, rect£$(0) 

The region specified by the handle hand! is set equal to 
the rectangle rect%. A region is not created by this, but must 
have been previously defined with NewRgn. 

You may use either of these two statements in place of the 
OpenR gn and CloseRgn sequence above as desired. 

Use GetClip to set a region to the current clipping region 
and SetClip to set the clipping region to a different region. 
You may want to use SetClip to switch back and forth 
between different clipping regions. 

Have any interesting programs you have created after 
experimenting with clipping regions? Feel free to share them 


with others by sending them in to MacTutor. 
'Region/Clip Demo 

"by Dave Kelly 

'MacTutor ©1986 

LIBRARY" ToolLib” 

DIM R&(3), OvalR%(3), fontinfo%(3), pattern&(3) 
x1$-50:y1$-20:x23-450:428-200 

SetRect R&(O),x 1%, y1%,x2%, y2% 

SetRect pattern%(@), &HAA, &HAA, &HAA , &HAA 
WINDOW 1,"",(2,30)-(508,275),4 

CALL BACKPAT CVARPTR(pattern%(@))) 

CLS 

SetRect pattern%(0),0,0,0,2 

CALL BACKPATCVARPTR(pattern%())) 

CALL TEXTSIZECO) 

getfontinfo fontinfosC0) 
fhZsfontinfo$COD*fontinfo$C1) 
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handle!=8 
01dReg!=0 
NewRgn 01dReg! 
getclip OldReg! 
NewRgn handle! 
OpenRgn 
FRAMEOVAL VARPTRCRZCO)) 
CloseRgn handle! 
Setclip handle! 
CALL MOVETOCx 1%, y 1%) 
FOR i=1 TO 18 
CALL MOVETO (x 1%, 1%+i*f hf) 
FOR j=1 TO 6 
drawtext "Read Mac Tutor! " 
NEXT j 


NEXT i 

CALL PENSIZE (2,2) 

framergn handle! 

disposergn handle! 
dh¥=58 : dy%=25 

x 18=x 1$*dh$ : y 18=y 1$*du$ 
X2%=x2%-dh¥ :y2$-428-du$ 
SetRect R&CO),x1%,y1%,x2%, y2% 


NewRgn handle! 
OpenRgn 

FRAMEOVAL VARPTRCR£CO2) 
CloseRgn handle! 


Setclip handle! 
cs 


CALL MOVETOCx 1%, y 1$) 

FOR i=1 TO 18 
CALL MOVETO (x 1%,y1%+i* fh) 
FOR j= 1 T0 6 

drawtext "It's Grrrreat! " 

NEXT j 

MEXT i 

fremergn handle! 

disposergn handle! 

Setclip OldReg! 

disposergn OldReg! 

LIBRARY CLOSE 

END 
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Basic School 


Play the Talking HangMan Game! 


This month I would like to thank Clear Lake Research for 
kindly sending me a copy of their SpeechLib Library. 
[Available through MacTutor's Technical Software Store. -Ed] 
As computers become smarter and smarter, we are sure to find 
those that will do many of the same tasks that humans do. 
Already, I get sales recordings on my telephone from some 
computer that goes through a list of numbers and presents 
their sales pitch. We can't even comprehend how far 
computers will take us in the future. In fact, in 1979 when I 
bought my first Apple ][+, I was thrilled to have that much 


Dave Kelly 
Engineer 
MacTutor Editorial Board 


English or phonemic spellings. Phonemic spellings produce 
much better sounding speech and are highly recommended. 
However, English is much easier to use. Phonemic sounds 
are shown below: 


By mixing combinations of these phonemic spellings, you 
can form the sound that you want. You can see why it takes 
more time to program in phonemic spellings; each sound 
must be matched to the phonemes. 


capability. I never thought that computers would become PHONEMIC SOUNDS 
much different, until Macintosh came along. 
I've seen a large variety of speech synthesizer VOWELS 
cards for the Apple ][. When they first came AA hot AX about IX solid 
out, the speech was hardly recognizable. I've AE bat EH bet IY beet 
seen good ones and bad ones. When I got my AH under ER bird OH border 
Macintosh, I was excited that the Mac had a AO talk IH bit UH look 
built in synthesizer, however, I was disappointed 
to find that the software to program the AX and IX should not be used in stressed syllables! 
synthesizer had not been written. Well, enough 
talk The CLR SpeechLib Libraries provide a CONSONANTS 
low cost way to provide speech from within B but K camp T toy 
your MSBASIC programs (version 2.0 or CH check L yellow TH thin 
greater). IC loch M men V very 
MacinTalk is a copyrighted program of D dog N men W away 
Apple Computer, Inc. licensed to Clear Lake DH then NX sing Y yellow 
Research to distribute for use with SpeechLib. F fed P put Z has 
SpeechLib allows you to use the MacinTalk G guest R red ZH pleasure 
speech synthesis system developed by Apple MH hole S sail 
from MSBASIC. SpeechLib statements are J judge SH rush 
similar to other CLR library statements as we 
have discussed in past issues of MacTutor. DIPHTHON 
Speaking of libraries, I hereby wish to make AW power EY made OY boil 
a correction to a statement that I made a couple AY hide OW low UW crew 
of months ago. I stated that for some reason 
when you use DEFINT a-z an error results. PECI YMBOL 
Well, the error was partially mine. When you DX pity Q kitt_en RX car 
call a library, the library name (example: LX call QX silent vowel UL=AXL 
SpeechOn) will be specified as if it were an 
integer variable if you have used DEFINT a-z. SHORT HAND SYMBOLS 
The library name must be declared as a single IL=IXL IM=IXM IN=IXN 
precision variable type by placing an UL-AXL UM=AXM UN=AXN 
exclaimation point after the library name 
(example: SpeechOn! ). Therefore, when you digits 1-9 stress marks - phrase delimiter 
want to use DEFINT and libraries, you should ; sentence terminator — , clause delimiter 
use an exclaimation point after the library name. ? sentence terminator — ()  — noun phrase delimiters 


If you are using MacinTalk from another 
language, parts of the following discussion may 
be useful to you. SpeechLib accepts either 
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Also included with the SpeechLib disk is the program 
ExceptionEdit. This program was witten by Apple to be used 
to create a dictionary of words and their phonemic spellings. 
When a word in the dictionary is encountered by MacinTalk, 
the phoemic spelling in the dictionary determines the 
pronounciation of the word. This makes using English 
instead of phonemic spellings possible for hard to pronounce 
(or spell) words. It is possible to mispell words in english to 
fool' MacinTalk into pronoucing them correctly. If you do 
this, then the exception dictionary is not necessary. However, 
you may want to read aloud a text file which must have correct 
spellings. You should create an exceptions dictionary in this 
case. 

There are two SpeechLib statements used to initialize the 
speech output. First open the Library and define variables for 
the handle! (SpeechHand!-0), for possible speech errors 
(SpeechErr%=0), and for the phonemic spelling of the string 
to be output (Phon$=""). The statement SpeechOn 
"",SpeechHand!,SpeechErr™ turns on and initializes 
MacinTalk. 

To use english spellings with SpeechLib, you first must 
put the desired text into a string (example: Eng$). MacinTalk 
understands phonemic spellings, therefore your string must be 
converted before the string can be spoken. The SpeechLib 
command for this is: 


ReaderString SpeechHand! ,Eng$, Phon$,SpeechErrs. 


To use phonemic spellings or the converted Eng$ spelling 
(Phon$), you use the statement: 


SoundOutString SpeechHand!, Phon$, SpeechErr$ 


Statements are provided to change the pitch, mode and 
speech rate of the speech (SpeechPitch and SpeechRate). 
The pitch can range from 65-500. The mode selects a natural 
or a robotic sounding voice. The speech rate can be adjusted 
from 85-425 words per minute. The volume is controlled by 
poking the volume desired into address &H208. The range of 
the volume is 0 to 7, where 7 is the loudest. 

The best way to sample the speech and test out phrases 
you want to use is to use the speech demo provided on the 
SpeechLib disk. This way you can find out how words sound 
before using them in your program. Phonemic spellings take 
much longer time to program until you start to learn the 
phonemic spelling chart. Some words may take some work to 
get them to sound just like you want. In fact, there are some 
words that I couldn't quite get to sound like I wanted. Be 
careful to use uppercase only for phonemic spellings and 
follow the Phonemic Spelling table to obtain the desired 
sounds. Try some out till they have the sound you want. The 
limitation is in the capabilities of the speech synthesizer. I 
found that the first few sentences that I heard were hard to 
understand. After getting used to it, I have no trouble 
distinguishing the speech. I tried it out on my 4 year old boy 
who seemed to catch on to the sound after a few sentences 
also. All things considered, the Macintosh still has a better 
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synthesizer than I had seen prior to it's design in the early 
eighties (83-847). 
HANGMAC 

The inspiration for HangMac came from the hand held 
Speak-N-Spell games. Word type games are probably the 
most suited to adding speech. I give you this example to 
show how speech could be added to a program, even after it 
was already written. In fact, most of the programming time 
was spent on the game itself and not the speech. Adding 
speech was a very simple task. 

HangMac was written first without speech. Two basic 
modules were added to introduce speech. The first one I call 
InitTalk. 


InitTalk: 
SpeechHand!=9 :SpeechErr$-0 :Phon$z" " 
her tz&= 190 : modeZ=6 : Wpm&= 125 
SpeechOn! "",SpeechHand! , SpeechErrg 
SpeechPitch! SpeechHand! ,hertz&%, mode& 
SpeechRate! SpeechHand! , Wpm$ 
POKE &H208,5 
RETURN 


InitTalk sets up all the variables used by 
SpeechLib. The rate, pitch, volume and mode is set 
up here. The other major speech module is Speakup: 


Speakup: 
ReaderString! SpeechHand!, Eng$,Phon$, SpeechErrs 
Sound0utString! SpeechHand! ,Phon$, SpeechErrs 
RETURN 


Speakup converts the string Eng$ to Phonemic 
spelling (Phon$) and outputs Phon$ to MacinTalk. Other 
than these two routines, the only requirement is to open and 
Close the library properly. A note: MacinTalk must be on the 
same disk as BASIC in order to work. Any exception 
dictionaries must also be on the same disk as BASIC in order 
to work. You may note that some words sent to the 
SpeechLib routines appear to be mispelled. This is to correct 
some mispronounciations of english spelled words. Don't 
attempt to correct the spellings or the words just won't sound 
right. 

The LIBRARY statement specifies the disk and filename 
of the SpeechLib library. Be sure that your disk has the right 
name or modify the LIBRARY statement to match the name 
of the disk and filename of the SpeechLib Library. The fact 
that all this stuff has to be contained on one disk makes this 
just a bit of a hassle. An 800K disk drive or a hard disk 
should solve that problem. 

Please note that HangMac has not been tried out on a 
128K Mac. When using libraries, more heap space may be 
required. The SpeechErr% variable returned in most of the 
SpeechLib calls should return a zero. HangMac does not 
check for this, so if you get an speech error, check to see what 
value SpeechErr% returns by typing PRINT SpeechErr% in 
the command window and hitting return just after the error 
occurs. If SpeechErr% is not zero after the SpeechOn call, 
then MacinTalk could not be opened. The most likely 
problem is that MacinTalk is not on the same disk as BASIC. 
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Another possiblity is that you have run out of heap space. 
Use BASIC's FREQ to check on available memory space and 
BASICs CLEAR statement to allocate more or less as 
necessary. HangMac is already set up for a data segment size 
of 20000. Without the statement CLEAR 20000! at the 
beginning of the program, the heap size is too small, which 
causes the disk to run alot more. 

SpeechLib also provides a more efficient memory 
management method by storing strings on the heap. The 
strings may be used later by referencing the desired string. 
HangMac does not use this feature. If you use it, you may 
have to watch your heap space more closely. If you are using 
other CLR (or others) libraries with SpeechLib, memory 
management is more of a concern. 

HangMac automatically checks to see if you have CLR 
SpeechLib and disables all the talking parts of the program 
through the use of the variable talk. This enables you to run 
HangMac without sound if you don't have CLR SpeechLib. If 
speech is enabled, the speech can be turned on or off at any 
time (it speeds up the game) by selecting the speech menu. 

I recommend, before you start to play HangMac, that you 
add more words to the program. I have started with 15 words 
(words related to the MAC). To add words, add to the DATA 
statements at the end of the program. Next change the line 
toward the beginning of the HangMac program which sets the 
variable number to the number of words (currently 15). 
That's all there is to it. The more words you have the more 
chance there is of getting a different word every time. When I 
was first creating the program I started with five words, and I 
often got the same word more than once. The words are 
randomized each time a new word is selected, so you don't 
know which word will be used. 

Choose Instructions for a quick overview of the program. 
If speech is turned on, the instruction window will let you 
choose a TALK button to have the instructions read to you. 
Choose OK to close the instruction window. 

Choose Start Game to begin HangMac. Most of your 
selections will have an audio response if the speech is turned 
on. Three windows are displayed. The first window shows 
the characters which have been used or guessed already. The 
second window shows the word to be guessed by displaying 
blanks for the characters until they are guessed correctly. You 
may type the whole word in if you think you know what it is. 
If you are wrong a new part of the HangMac man is drawn on 
the hanging post. You have 10 tries and then you're hung. 

This may not be the best Hangman game you have ever 
seen, but it must be the first one you have had talk to you. 
HangMac will mostly be exciting for younger aged children. 
Even now as I approach the deadline for this column, my 
young sons are leaning over my shoulder waiting for me to 
finish so they can try it. Well, I guess it's time to play. 


"HANGMAC 
"OMACTUTOR, 1986 
‘by David Kelly 


Initialize: 


CLEAR, 20000 ! 
DEFINT a-z 
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HangMac 


Copyright 9MacTutor, 1986 
by David Kelly. 


€ File Speech 


ar AURIS AA NARNIA EE CEEE 


AR SA ey te ru PT n SNR INR I IV SIS P It i P Pa a o da v 


DIM wordchar( 1) 

felse-0:true-NOT false 

talk=true :number= 15 

DIM wordarray$(number ) 

ON ERROR GOTO 10 

LIBRARY "CLR SpeechLib:SpeechL ib" 


9 :0N ERROR GOTO 0 


IF talk=true THEN GOSUB InitTalk 
FOR i=1 TO number 
d rn wordarray$C i) 

i 


blank$="" 


FOR i=! 40:blenk$-blenk$*" ":NEXT i 
NDO 


, File" 

, Instructions" 
, otart Game" 

, Quit" 


, OFF" 
lse THEN MENU 2,0,0 


idleloop: GOTO idleloop 


menuevent: 


A CH AA ANE A MA tat AG at A AANA ALL PLNRA RS SALSA NANA NERA 


TOPPED 


a t SH E INIT a eee lr ra n a fnt a Ia 


nenunumber-MENUC?O):IF menunumber=2 THEN Speechmenu 


nenuitem-MENUC 12 : MENU 
MENU 1,8,8 


ON menuitem GOSUB Instructions, Start, Quit 


RETURN 


Speechmenu: 


menui tem= C D: MENU 

IF menuitem=1 THEN MENU 2, 1,2:MENU 2, 
IF menuitem=2 THEN MENU 2, !, 1: MENU 2 
MENU ON 


RETURN 


2 
2 


: talkstrue 
:talk=false 
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InitTalk: 


SpeechHand ! =9 : SpeechErr%=@ : Phon$="" 
her tz%= 190 : modeZ=0 : Wom%= 125 

SpeechOn! "",SpeechHand! , SpeechErr% 
SpeechPitch! SpeechHand! ,hertz%, mode% 
SpeechRate! SpeechHand! ,Wpm$ 

POKE &H208,5 

RETURN 


Quit: 


GOSUB ClearKeyboard 

IF talk=true THEN Eng$="Good buy. Play again 
Sometime.":GOSUB Speakup 

aa THEN SpeechOff! SpeechHand!  :LIBRARY 


index=INTCRNDC 1)*number ) 
IF index=9 THEN Start 
word$-wordarray$C index) 
GOSUB HangSetup 
ERASE wordcher 
DIM wordcher (LENCword$)) 
FOR i=1 TO LENCword$) 

wordchar (i )=false 

i 


usedchar=@ : used$=""" 
WrongGuess-£ : lose=false 
TEXTFONT(2) 

TEXTSIZEC 14) 

TEXTFACEC 1) 

wf lag=false 

sumword-0 

GOSUB DisplayWord 

IF talk=false THEN inputchar 
Eng$="Your word is "*STRÉC(LEN(word$2)*" characters long." 
GOSUB Speakup 


W 1 

GOSUB DrawHangPost 

GOSUB ClearKeyboard 

EDIT FIELD 1,"",(95, 198)-(4 18,218), 1,2 
IF talk=false THEN char loop 
Eng$="Please choose a letter" 

GOSUB Speakup 


char loop: 


d-DIALOG(2) 

IF d6 THEN char loop 

cher$-UCASESCEDIT$C 12) 

IF char$="" THEN inputchar 

IF talk=false THEN checkchar 

Eng$="You have selected, “tchar$+". " 

IF cher$«"A" OR char$>"Z" THEN Eng$-Eng$*" That character 
is not aloud." 

IF INSTRCused$, char$)<>@ THEN Eng$-Eng$*"That letter is 
elready used." 


Wrong: IF char$« word$ AND LENCcher$2€ 1 THEN 


Eng$=Eng$+"WRONGE ! " 
GOSUB Speakup 


checkchar : 


IF cher$«"A" OR cher$ »"Z" THEN inputchar 

IF INSTRCused$,char$209 THEN inputchar 

IF cher$-word$ THEN GOSUB foundword 

IF cher$o word$ AND LENCchar$)<> 1 THEN 
WrongGuess=WrongGuess+ 1:GOSUB DrawHangMac :GOTO 
inputchar 
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used$=used$+char$+" " 

oldsumssumword 

sumword- 

FOR i21 TO LENCword$) 
IF char$=MID$Cword$, i, 1? THEN wordcharCi)strue 
Sumword-wordchar( i )*sumword 


NEXT i 

Eng$="That's " 

IF oldsum=sumword THEN WrongGuess-WrongGuess* 1: 
Eng$-Eng$* "WRONG ! " 

IF sumword=-LEN(word$) THEN wf lag=true 

IF (wf lag=false) AND Coldsum<>sumword) THEN 
Eng$-Eng$*"Right. There is at least one " *char$*" in 
the word." 

IF wflag=true THEN Eng$=Eng$+"Right. You have guessed 
the word." 

IF talk=true THEN GOSUB Speakup 

GOSUB DisplayUsedChars 

GOSUB DrawHangMac 

GOSUB DisplayWord 

IF wflag=false AND lose=false THEN inputchar 

IF wflag=true THEN Eng$-"You Won. The word is "*word$*". 
Select Start Game to Play again." 

IF lose=true THEN Eng$="You're dead. The word is 
"tword$*". Select Start Game to Play again." 

IF talk=true THEN GOSUB Speakup 

FOR i=1 TO LENCword$) 

wordchar (i )=true 
i 

WINDOW 1 

EDIT FIELD CLOSE 1 

MENU 1,6, 1 

RETURN 


HangSetup: 
WINDOW 1,"HangMac", (18, 100)- (590, 320),2 
TEXTFONTC2) : TEXTSIZEC 18 ) : TEXTFACEC 1) 
LOCATE 1, 1:PRINT "HangMac" 
TEXTSIZEC 10) : TEXTFACECO ) 
PRINT " Copyright ®MacTutor, 1986" 
PRINT" by David Kelly." 
WINDOW 2,"",(95,30)-(410,452,2 
WINDOW 3,"",(95,65)-(410,80),2 
WINDOW 1 
RETURN 


foundword: 

wf lag=true 

FOR i=1 TO LENCword$) 
wordchar (i )=true 
NEXT i 
RETURN 


DisplayWord: 
WINDOW 3 
LOCATE 1,1 
PRINT blank$:LOCATE 1,1 
IF lose=true THEN PRINT word$; :RETURN 
FOR j=1 TO LENCword$) 
IF wordchar(j)=true THEN PRINT MID$Cword$, j, 1); 
ELSE PRINT "_ "; 
NEXT j 
RETURN 


DisplayUsedChars: 
IF LENCchar$ >> 1 THEN RETURN 
VINDOW 2 
LOCATE 1,1 
PRINT used$; 
RETURN 


DrawHangMac: 
WINDOW 1 
GOSUB DrawHangPost 
IF WrongGuess >=1 THEN CIRCLE(250,35),25 
IF WrongGuess »-2 THEN CIRCLE(260,25),5 
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IF WrongGuess »-3 THEN CIRCLE(249,25),5 
IF WrongGuess >=4 THEN LINE(240, 45)-(260, 45) 

CALL PENSIZE(2,2) 

CALL MOVETOC 259, 69) 

IF WrongGuess »-5 THEN CALL LINETO(250, 125) 

IF WrongGuess >=6 THEN CALL LINE(C45, 45) 

IF WrongGuess »-7 THEN CALL MOVETO(C250, 125):CALL 
LINE(-45, 45) 

IF WrongGuess >=8 THEN CALL MOVETO(C259,92)5: CALL 
LINEC25, -25) 

IF WrongGuess >=9 THEN CALL MOVETO(250,90):CALL 
LINEC-25, -25) 


CALL PENNORMAL 

IF WrongGuess >=9 THEN CALL MOVETO(255,20):CALL 
LINEC 12, 102: CALL MOVETO(255,30): CALL 
LINEC 10, - 10) 

IF WrongGuess >=9 THEN CALL MOVETO(C235,20): CALL 
LINEC 10, 105: CALL MOVETOC235, 30): CALL 
LINEC 10, - 10) 

IF WrongGuess >=9 THEN lose=true 

RETURN 


DrawHangPost: 


CALL PENSIZE(4, 4) 
CALL MOVETOC250,5) 
CALL LINETOC310,5) 
CALL LINETOC3 10, 185) 
RETURN 


ClearKeuboard: 


key z"X" 
WHILE key$ 0"" 
key$=INKEY$ 


RETURN 
: IF ERR=53 THEN talk=false 


RESUME 5 
END 


Instructions: 


WINDOW CLOSE 2 

WINDOW CLOSE 3 

WINDOW 1,"Instructions",C10,302- (500,330), -2 

TEXTFONTC2) : TEXTSIZEC 18) : TEXTFACEC 1) 

LOCATE 1,15:PRINT "HangMac" 

TEXTSIZEC 12) : TEXTFACECO ) 

LOCATE 3,1:PRINT "HangMac is the audio version of the 
treditional game of"; 

PRINT" Hangman. To play":PRINT'the game just choose "; 

TEXTFONTCOD :PRINT"Start Game"; : TEXTFONT(2) 

PRINT" from the File menu. The hanging post is" 

PRINT “drawn and you may start guessing letters by typing 
them onto the base of" 

PRINT'the hanging post. The uppermost window will 
display the characters which" 

PRINT"you have used. The next window shows the 
characters, or blanks for the" 

PRINT"word that you are guessing. Each time you miss, a 
new part of the HangMac" 

PRINT"man will be drawn until the entire body is drawn. 
If you guess wrong ten" 

PRINT"times then you lose. Type the whole word to guess 
the word." 

PRINT'"This program features CLR SpeechLib procedures for 
calling Macintalk." 

PRINT"To use the speech feature you must have CLR 
SpeechLib Cavailable from" 

PRINT'Clear Lake Research, 5353 Dora Street, Suite 7, 
Houston, Texas 77005" 

PRINT"(800-835-2246 X 199). However, the program will 
still work without" 

PRINT'the speech libraries being available.” 

PRINT:PRINT"HangMac, Copyright ®MacTutor, 1986, by David 
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Kelly." 

BUTTON 1, 1, "0K", (445,2602-(475,290) 

IF talk=true THEN BUTTON 2, 1, "TALK", (365,2602- (425,290) 
WaitforButton: 

WHILE DIALOGCO) O 1: WEND 

buttonpushed = DIALOG( 1) 

IF buttonpushed-2 THEN GOSUB SpeakInstructions:GOTO 

WaitforButton 

BUTTON CLOSE 1 

BUTTON CLOSE 2 

WINDOW CLOSE 1 

MENU 1,0,1 

RETURN 


SpeakInstructions: 

BUTTON 1,9:BUTTON 2,0 

Eng$-" HangMac is the audio version of the traditional 
game of Hangman. To play" 

Eng$-Eng$*" the game just choose Start Game from the File 
menu. The hanging post is" 

Eng$-Eng$*" drawn and you may start guessing letters by 
typing them onto the base of" 

Eng$=Eng$+" the hanging post. The uppermost wyndoe will 
display the charactors which" 

Eng$-Eng$*" you have used. The next wyndoe shows the 
characters, or blanks for the" 

Eng$-Eng$*" word that you are guessing. Each time you 
miss, a new part of the HangMac" 

Eng$-Eng$*"-man will be drawn until the entire body is 
drawn. If you guess wrong ten" 

Eng$-Eng$*" times then you luse. Type the whole word to 
guess the word." 

ReaderString! SpeechHand! ,Eng$,Phon$, SpeechErrs 

SoundOutString! SpeechHand! , Phon$, SpeechErrs 

Eng$="This program features CLR SpeechLib proseedures for 
calling Macintalk." 

Eng$-Eng$*" To use the speech feature you must have CLR 
SpeechLib (available from" 

Eng$-Eng$*" Clear Lake Reserch, 5353 Dora Street, sweet 7, 
Huse ton, Texas 77005." 

Eng$=Eng$+" phone- eight hundred 835-2246 extension 199. 
However, the program will still work without the speech 
lybrar ies" 

Eng$=Eng$+" being available." 

Eng$=Eng$+" HangMac, Copy right MacTutor, nineteen eighty 
six, by Dayvid Kelly." 

ReaderString! SpeechHand! ,Eng$, Phon$, SpeechErr% 

SoundOutStr ing! SpeechHand! , Phon$, SpeechErr$ 

Eng$="":Phon$="" 

BUTTON 1, 1:BUTTON 2,1 

RETURN 


Speakup: 
ReaderString! SpeechHand!, Eng$,Phon$, SpeechErr’ 
SoundOutString! SpeechHand! ,Phon$,SpeechErrs 
RETURN 


‘Add additional words Cas you please) 

"by adding to the DATA statements below 
‘change the variable ‘number’ at the beginning 
‘of the program to reflect the number of words 
‘available. 


DATA "MACINTOSH", "MOUSE", "DISK" , "DESKTOP", "CURSOR" 
DATA "ICON", "KEYBOARD" , "WINDOW" , "MENU" , "PRINTER" 
DATA "MODEM" , "BYTE" , "MEMORY", "PROGRAM" , "DATA" 


Basic School 


MENU DEMO.RUN 
Softworks Basic Shows Toolbox Flavor 


Welcome to this months BASIC column. I'm excited this 
month because I have something new to show you (brag 
about??). About 3 or 4 weeks ago someone asked me via the 
Mousehole if I was going to feature anything about the new 
compilers that have come (are coming?) out on the market. 
At that time there were no compilers available except a few 
that advertised their "Vaporware" in the major magazines. 
That has prompted me to explore some of the new BASIC 
products that are coming out. As you know MacTutor has a 
general policy of not doing reviews of any products, especially 
" Vaporware". At the time of this writing I have only received 
one (the only new one that you can actually buy). Softworks 
Limited has been advertising in MacTutor for the past few 
months and has released their Personal Basic for $99. Two 
other new BASICS are due out very soon, ZBASIC and True 
BASIC. 


One of the most annoying things about BASIC (I hear this 
complaint all the time from C and Assembly programmers) is 
that BASIC is so slow. Well, they're right! Microsoft has 
had a great advantage by having the only BASIC product for a 
couple of years now. Most everything that I want to do with 
my Mac I can program in Microsoft BASIC. Well, almost 
everything. You see, when I write a program I like to write a 
program that looks and behaves like one that I would pay for. 
If the program doesn't look professional to me then I don't feel 
that it is finished. I have to make some exceptions in this 
column with editorial deadlines, but that's to be expected. 


Well, lets face it, there are some things that just can't be 
done in MS Basic. Most of these things could be resolved 
with a few well placed calls to the Macintosh ROM routines. 
When you learn how to do Menus, dialogs, windows etc. in 
MS BASIC, you are in fact just learning how to use the 
Microsoft implementation of the toolbox. You open or close 
Windows their way. You create menus their way. You 
monitor events their way. BASIC programmers have been left 
out in some ways from the real Macintosh. The very brief 
encounters we have with Inside Macintosh when programming 
in MS BASIC are really too few to even mention. Of course, 
with Library subroutines attached to BASIC you can have 
access to some of the toolbox but the library must be 
accessible. Frustrating? Well, maybe. Some BASIC 
programmers out there may not need more than what has been 
provided. Others of us would like to see MS BASIC with full 
toolbox support without having to make sure that the right 
library is on the disk. Try writing a desk accessory in MS 
BASIC. Right now it can't be done. 
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Dave Kelly 
MacTutor Editorial Board 


Benchmark Comparison 


Softworks Limited Personal Basic is a step in the right 
direction. Take a look at the Sieve Benchmark Test which 
they have included in their ads. One of the first things I have 
tried to do is verify the results of their tests. I was suprised to 
see that it depends on which version of the Sieve Benchmark 
that you have. I have aquired at least two of them and both 
give different times. I recommend that you be sure that you 
only do comparisons with the same versions of the Sieve. 
One version I have is written in MS BASIC and uses WHILE- 
WEND. Softworks BASIC doesn't support WHILE-WEND 
So a good comparison can't be made with that version. The 
version that I recieved with Softworks BASIC (example 
program) runs under either MSBASIC or Softworks BASIC 
with very minor modification. The major change was 
replacement of the comment symbol (MS BASIC uses " ' " ; 
Softworks uses " ! " ). The Sieve is a fairly good test of speed 
of a computer. The results of the Sieve provided with 
Softworks BASIC is as stated in their ad: Softworks Basic 53 
seconds (10 iterations averaged) and MS BASIC 120+ seconds 
(depending on the version and precision). Another test that we 
like at MacTutor, tests the accuracy as well as speed: 


! Softworks BASIC Benchmark 
40 time1=TIME 

50 s=0 

100 x=0 

200 FOR n=1 TO 1000 

300 s=s+x*x 


400 x=x+.00123 

500 NEXT n 

600 PRINT s,x 

800 Totaltimeztime2-time1 

900 PRINT "Elapsed Time = ",Totaltime," Seconds." 
950 input a ! halt to see screen 


The only change needed to run this in MS BASIC is that 
the statement TIME must be changed to TIMER in lines 40 
and 700. The results of the test are: 


Product S X 
Softworks BASIC: 503.544 1.23 
503.545 1.230001 
503.54380215 1.23 


MS BASIC 2.1(b): 
MS BASIC 2.1(d): 


By the way, very few computers ever get the right 
answers. [The right answer is 503.54380215 exactly. 
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Anything else denotes error in the math routines due to binary 
representation and/or rounding. As an example, an HP 9836 
desktop computer runs this same Basic benchmark in 1.03 
seconds with the exact result while an IBM PC running 
MBASIC returns 503.545 in 7.5 seconds, and an Apple II 
with Applesoft takes 26 seconds to calculate 503.543832. - 
Ed.] 


Before I highlight a few of Softworks BASIC's features, 
please keep in mind that basic BASIC has been enhanced on 
all of the more recent computers. When I was first introduced 
to computers about 10 years or so ago, BASIC consisted of 
LET, PRINT, FOR-NEXT, GOTO, DATA, INPUT and a few 
others, but that was all. In MS BASIC we have many new 
enhancements such as no line numbers, line labels, WHILE- 
WEND, IF-THEN-ELSE, PRINT USING etc. Remember 
that different versions of BASIC implement these 
enhancements in different ways. If you program in PASCAL, 
C or other languages that have made use of the toolbox, you 
will find many aspects of Softworks BASIC familiar to you 
just by virtue of having access to the toolbox. This will 
make programming seem a little strange to you if you are used 
to MS BASIC. 


Softworks Features 


Ok, lets talk about what Softworks BASIC has. Basically 
speaking, of course, Softworks has provided the standard set of 
BASIC commands with enhancements. Some of these 
enhancements include IF-THEN-ELSE, PRINT USING, MIN, 
MAX, FACTorial, FIX, HEX, OCT, BIN, TIME and others. 
It is not possible to go into all of them at this time. There 
are quite a few Softworks commands that are only 
implemented in Softworks BASIC, to my knowledge. Some 
of the other new BASIC products may have implemented 
some similar (or maybe even some of the same) type 
commands. Some examples of these are toolbox, XCALL, 
ISAM, MAP, BYTEORDER, BYTEMOVE, BSTR, PSTR, 
and WORD among others. One command that stands out is 
the MAP command. A distinct feature of Softworks BASIC 
is the ability to reserve space for complex data structures like 
those in languages such as C and PASCAL. This allows the 
user to handle almost any conceivable set of data as a coherent 
unit or by its parts. As an example look at the demo program 
for the Mapped variable named theEvent. 


map1 theEvent 
map2 what,b,2 
map2 message,b,4 
map2 when,b,4 
map2 where 
map3 where'v,b,2 
map3 where'h,b,2 
map2 modifiers,b,2 


The MAP statement reserves space for the variable 
theEvent. The variable theEvent is divided into different parts, 
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what, message, when, where, etc. You may refer to any one 
of them separately or refer to the whole variable, theEvent all 
at one time. The ,b,2 following the variable what tells Basic 
that what will be a 2 byte binary or integer variable. As you 
can see, this allows you to take the PASCAL procedures and 
variables in Inside Macintosh and structure them in your 
program. The set of toolbox commands available appears to 
be complete, with over 500 commands available. It is 
possible to write simple programs without doing any toolbox 
calls (a window is predefined for you to use for output), but to 
make your application look like a Macintosh application you 
will have to dig into Inside Macintosh and learn how to use 
the toolbox. A beginner could use Softworks BASIC, but 
would not be able to have Mac-like applications without 
obtaining skill at using Inside Macintosh. 


One of MS BASIC's strengths is the ability to easily 
create Mac-like programs. It may take some time and 
experience to quickly write complete programs entirely using 
the toolbox. But since MS BASIC is slower (until a good 
compiler for it is finally released) and supports only a very few 
toolbox commands, Softworks BASIC is a likely candidate for 
experienced BASIC programmers. When some of the other 
"soon to be released" BASIC's are made available I will be 
comparing their strengths and weaknesses. 


Another feature of Softworks BASIC is the ability to mix 
strings and numerics in the same statement without 
conversion. All expressions are calculated from left to right. 
If, in the evaluation of a numeric expression, a string is 
encountered, an attempt is made to convert the string to the 
equivalent number (as in the VAL function). If it cannot do 
this, the string is treated as a zero. Similarly, if a number is 
encountered while processing a string expression, the number 
is converted to a string, and then operated on accordingly. 


These are the major strengths of Softworks BASIC as I see 
it: MAPed variables, complete toolbox access, faster speed 
than MS BASIC (note: the program is compiled into a type of 
p-code, not native 68000). You can either save your compiled 
programs and run them using the runtime application program 
(BRUN) or you may compile the runtime program with your 
own program to create stand-alone applications. Provision is 
made for launching into any other application you choose. 
You can call other routines written in other languages using 
the XCALL command. Many enhanced BASIC features are 
included. 


Softworks BASIC weaknesses are: It is not possible to 
call a Softworks BASIC program/routine from another 
programming language. The .REL type standard is not 
supported. Stand alone applications must include all the 
runtime code, regardless of how much of it is actually used. 
Also, there is a one time $25 license fee for each stand alone 
application that you intend to distribute sell to other people. 
Softworks has told me that this fee is ONLY for programs 
you expect to get gain from, i. e. commercial. They say this 
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license fee does not apply to public domain programs that you 
may write. In fact, it should be noted that the runtime package 
has already been made available on Compuserve. The 
compiler is still considered the key to Softworks BASIC and 
is not free. Another disadvantage: It is not possible to write 
desk accessories because the stand alone applications are not 
native 68000 and the runtime program must be included (that 
takes at least SOK or more) There are still some 
compatability problems with HFS and Softworks BASIC. 
For now, be sure to use the HFS Fix routine by Andy 
Hertzfeld or the Editor (MDS editor) used by Softworks will 
not find files properly. [Getting the latest Editor, 2.0d2 or 
1.53 should solve this problem. -Ed.] 


Only you can decide if Softworks BASIC is "right" for 
you. Beginners may have some difficulty becoming 
experienced using the Macintosh interface via the toolbox. 
Keep in mind that this is the first released BASIC to include 
all the toolbox commands. The manual included with 
Softworks Basic lists the toolbox commands which are 
supported, but not in detail. You will have to refer to Inside 
Macintosh PASCAL procedures to find out how to use 
toolbox commands. 


The Demo Program 


The demo program could have been written in either C or 
PASCAL with about the same amount of difficulty (or ease) if 
you know either C or PASCAL. The intent of the demo is to 
demonstrate how to access the Macintosh toolbox from 
Softworks BASIC. This demo could be considered a skeleton 
for use in beginning the structure of any program that you 
may write. In future articles regarding Softworks BASIC we 
will try to fill in the gaps that are skipped in the demo. 


The first step to accomplish before beginning work on 
your application is to become familiar with the parts of Inside 
Macintosh that pertain to what you intend to do. The demo 
requires information from the Window Manager, Event 
Manager, Menu Manager and the Softworks Personal BASIC 
manual. One thing I wish to point out is that each of the 
variables mapped in the beginning of the program have been 
taken from Inside Macintosh with very little modification. In 
general, Pascal INTEGER variables are 2 bytes and MAPed as 
2 byte integers (example: map2 what,b,2) where what is an 
INTEGER variable listed as part of the ^ EventRecord 
PASCAL record in the summary section of the Event Manager 
(Inside Macintosh). You can see that PASCAL record 
structures are replaced by MAPed variables in Softworks 
BASIC. 


In MS BASIC, most everything that uses the toolbox 
directly is done automatically for you by the BASIC 
interpreter. Not so in real toolbox programming. You must 
take care of every event that occurs (every movement or click 
of the mouse, every menu etc.) with the exception of system 
events which the system takes care of (like desk accessories). 
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€ File Edit Fonts Size 


MacTutor Window 


Fig. 1 Our demo program has fonts menu! 


This may come as somewhat of a surprise to those of you that 
are used to MS BASIC programming. No need to fear... the 
ROM routines provide what is needed to take care of 
everything. You just have to decide what you want to happen. 
After setting up variables, the demo program opens a window 
and then sets up the menu. The window manager takes care of 
opening the window. The program supplies the parameters 
required (as listed in Inside Macintosh) to use the window 
procedures. I will have more on windows at another time. 


Using menus in MS BASIC requires that you set up your 
menu with the MENU statement and then turn on menu event 
trapping with MENU ON. When a menu event occurs you 
can determine which path the program will take. 
Programming menus from the toolbox is very similar. You 
first set up your menus, then call the Event manager and 
observe what kind of event occurs. If a mouse click occurs 
(mouse down) you then check to see if the mouse is in the 
menu bar. If in the menu bar, you then call the menu 
manager to determine which menu and menu item was selected 
and act accordingly. 


toolbox NewMenu, 1, pstrCappleMark), menuhandle(1) 
toolbox AddResMenu, menuhandle(1), DRVR 


The NewMenu routine initializes the new menu. Notice 
that parameters passed in the routine are separated by commas 
in Softworks BASIC. The statement pstr in Softworks 
BASIC converts the string constant appleMark in Softworks 
BASIC format (terminated by a null byte) to a string in the 
Macintosh ROM format (preceded by a length byte). This 
menu will be titled @ and will be referenced by the handle 
named menuhandle(1). The items in the @ menu will be 
read from the titles of all resources of type DRVR. This is 
how all desk accessories are made available. The next menu 
Statements 


toolbox NewMenu,2,pstrC"File"),menuhandle(2) 
toolbox AppendMenu, menuhandle(C2),pstr(C"Quit") 
toolbox NewMenu,3,pstr(C"Edit"),menuhandle(3) 
toolbox AppendMenu, menuhandle(C3),& 
pstrC"Cut/X; Copy/C;Paste/V") 


define the File and Edit menus. This is done similar to the 
previous statements. The command keys are defined by using 
a slash and the command letter. (Refer to Inside Macintosh). 

It is recommended that the Edit menu be defined in this 
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standard way so that desk accessories, which use it, can take 
advantage of it. Some desk accessories will not be useful 
(example: the scrapbook) without being able to cut and paste. 


The final menu of our demo shows that font information 
can be read directly from resources also. 


toolbox NewMenu, 4,pstr("Fonts"), menuhandle(4) 
toolbox AddResMenu, menuhand1e(4), FONT 


The demo also shows us how to get the font size 
information into the size menu. The Getltem statement gets 
the font name from the menu. Then GetFNum gets the font 
number for the given menu name. Then using RealFont, the 
font size is checked. If the size exists then the menu item is 
drawn in outline mode. Note: the GetFNum routine is in 
error in the Softworks BASIC manual. This demo should 
show how to use the GetFNum statement. 


toolbox GetItem,menuhandle(4), i, ItemString$ 
toolbox GetFNum, ItemStr ing$, varptr(fontNum) 
toolbox RealFont, fontNum,size(1),sizestatus 


After the menus are set up, the program monitors all 
events in an event loop. This is similar to the method which 
may be used in MS BASIC for checking for dialogs, menus or 
other events. The toolbox routine, SystemTask, should be 
called at regular periods to enable the Macintosh to take care of 
system events, like desk accessory activity. You should call 
SystemTask often as possible, usually once every time 
through your main event loop. Call it more than once if your 
application does an unusually large amount of processing each 
time through the loop. (Note: Inside Macintosh states that 
System Task should be called at least every sixtieth of a 
second). GetNextEvent returns result eResult which indicates 
if an event has occured. The variable, what, which is part of 
the variable, theEvent , indicates what kind of event 
occured. It is now the responsiblity of the BASIC program to 
determine what action if any should be taken. This demo 
program has not fully developed all of the possible events, 
however, it is easy to add you own routines which control 
what will happen with each event. The possible events that 
could happen are: mousedown, mouseup, keydown, 
keyup, autokey, updateEvt, diskEvt, activateEvt, 
networkEvt, driverEvt and 4 user defined events. 


event’ loop: 
toolbox SystemTask 
toolbox GetNextEvent, everyEvent, theEvent, eResult 
if eResult = Ø goto event’ loop 
on what gosub mousedown, mouseup, keydown, & 
keyup, autokey, updateEvt, diskEvt, activateEvt, & 
networkEvt, driverEvt, appiEvt, app2Evt, app3Evt, & 
app4Evt 
goto event’ loop 


When the mousedown event occurs, the program flow is 
routed to the mousedown routine. The mousedown routine 
calls the FindWindow routine to determine where on the screen 
the mousedown event occured. If a menu has been selected the 
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cursor will be in the menu bar. Therefore, wResult will be 
equal to one, thus the program will call the inMenuBar 
subroutine. 


mousedown: 
toolbox FindWindow, where, varptr(whichwWindow), wResult 
on wResult gosub inMenuBar, inSysWindow, inContent,& 
inDrag, inGrow, inGoAway 
return 


The inMenuBar subroutine calls the MenuSelect toolbox 
routine. The DoMenu routine uses the result of the 
MenuSelect routine to determine which menu number and 
item was selected. 


inMenuBar : 
toolbox MenuSelect, where, mResult 
gosub DoMenu 
return 


This structured programming example provides a way for 
programs to be written which handle a multitude of events. It 
is advised that you use Inside Macintosh for the majority of 
your programming development. As you can see, BASIC has 
taken a backseat to the toolbox in most of this program. 


In future columns, I will add to the routines in this 
program so that other toolbox features can be explored. 


ISoftworks BASIC Demo 
!@MacTutor 1986 


IWindow Definitions 
map 1 wS torage, x, 256 
map 1 DragBoundsRect 
map2 r'top ,b,2, 4 
map2 r'left ,b,2, 24 
map2 r'bottm,b,2,338 
map2 r'right,b,2,508 
map! wBoundsRect 
map2 w'top ,b,2, 40 
map2 w'left ,b,2, 30 
map2 w'bottn,b,2,300 
map2 w'right,b,2,480 
nap1 WindowPtr ,b, 4 
map 1 nam$,s,32,pstrC"MacTutor Window") 
map 1 whichWindow,b,4 
mepl1 wResult,b,4 


IEvent Definitions 
mapi theEvent 
map2 what,b,2 
map2 message ,b,4 
map2 when,b, 4 
map2 where 
map3 where'v,b,2 
map3 where'h,b,2 
map2 modifiers,b,2 
map 1 eResult,f,,0 
map1 everyEvent,b,2,-1 


IMenu Def initions 

map 1 app leMark,x, 1, chrC&h 14) 
map 1 menuhandle(5),b,4 

mapi menu,b,2 

mepl menuitem,b,2 

map 1 mResult,b,4 

mapi MenuNumber,b,2 

map 1 MenuItem,b,2 
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mapi mrefNum,b, 4 


IMisc. Definitions 


map 1 true,b,2,-1 

map | felse,b,2,0 

map | currentfont,b,2, 1 
map 1 currentsize,b,2, 1 
map 1 z,f 

map | i,f 

map1 numberoffonts,b,2 
mapi numberofsizes,b,2,6 
mapi fontNum,b,2 

map! sizestatus,b,2 

map 1 size(6),b,2 


size( 1)=9:size(2)=19:size(3)=12:size(4)=14:size(5)=18 
size(6)224 


IBegin 

toolbox InitWindows 

toolbox Newwindow, wStorage, wBoundsRect, nam$, 
1, 16,1,0,0, WindowPtr 

toolbox SetPort, WindowPtr 

toolbox InsetRect,WindowPtr + 16,4,0 

toolbox ValidRect, varptr(CwBoundsRect ) 

gosub Set'Up ‘Menus 

event’ loop: 
toolbox SystemTask 
toolbox GetNextEvent, everyEvent, theEvent, eResult 
if eResult = Ø goto event’ loop 
on what gosub 

mousedown, mouseup, keydown, keyup, autokey, updateEvt, & 
diskEvt, activateEvt, networkEvt, driverEvt, epplEvt, & 
epp2Evt, a&pp3Evt, app4Evt 
goto event' loopend 


toolbox FindWindow, where, varptrCwhichWindow), wResult 
on wResult gosub inMenuBer, inSysWindow, inContent, & 
inDrag, inGrow, inGoAway 

return 


toolbox MenuSe lect, where, mResult 
gosub DoMenu 
return 
inSys¥indow: 
toolbox SystemClick, theEvent, whichWindow 
return 
nContent : 
toolbox FrontWindow,z 
return 
inDrag: 
toolbox DragWindow, whichWindow, where, DragBoundsRect 
return 


Way: 

toolbox TrackGoAway, WindowPtr,where,z 
if z then toolbox CloseWindow, WindowPtr 
return 


return 


return 

keyup: 
return 

autokey: 
return 

updateEvt: 
toolbox SetPort,WindowPtr 
toolbox BeginUpdate, WindowPtr 
toolbox EndUpdate, WindowPtr 
return 

diskEvt: 
return 

activateEvt: 
return 

networkEvt: 
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toolbox HiWord, mResult,MenuNumber 
toolbox LoWord, mResult,Menul tem 
on MenuNumber gosub apple, file,edit, fonts, sizes 
toolbox HiliteMenu,2 
return 
Te: 
toolbox GetI tem, menuhandle( 1),Menul tem, nam$ 
toolbox OpenDeskAcc, nam$, mrefNum 
return 
file: 
end 
return 


toolbox SystemEdit,MenuItem*1,z 
if z return 
! do cut or copy routines here. 
return 
fonts: 
toolbox CheckI tem, menuhandle(4),currentfont, false 
toolbox CheckI tem,menuhand1e(4),Menul tem, true 
currentfont = MenuItem 
toolbox DisposeMenu, menuhandleC5) 
gosub mekesizemenu 
toolbox DrewMenuBar 
for i=1 to 6 
if nstring$Ccurrentfont,i)strue then 
currentsize=i: i27 
next i 
toolbox CheckItem,menuhandle(5),currentsize, true 
toolbox textsize,sizeCcurrentsize) 
return 
sizes: 
toolbox CheckI tem, menuhandle(5),currentsize, false 
toolbox CheckI tem, menuhandle(5),Menul tem, true 
currentsize = Menultem 
toolbox textsize,sizeCcurrentsize) 
return 
Set ‘Up ‘Menus: 
toolbox InitMenus 
map 1 DRVR,x,4, "DRVR" 
map 1 FONT,x,4, "FONT" 
strsiz 32 
toolbox NewMenu, 1,pstrCapp]eMark), menuhendle( 1) 
Icreate apple menu 
toolbox AddResMenu, menuhandle( 12, DRVR 
ladd desk accessories 
toolbox NewMenu,2,pstrC"File"),menuhandle(2) 
Icreete file menu 
toolbox AppendMenu, menuhandle(2), pstr¢"Quit/Q") 
ladd ‘quit’ item 
toolbox NewMenu,3,pstr("Edit"), menuhandle(3) 
Icreete edit menu 
toolbox AppendMenu, menuhandle(C3),pstr( 
"Cut/X;Copy/C;Paste/V") 
ladd items 
toolbox NewMenu, 4, pstr ("Fonts"), menuhandle(4) 
Icreate fonts menu 
toolbox AddResMenu, menuhandle(C4),FONT 
ledd fonts 
toolbox CountMItems,menuhandle(4),numberof f onts 
map! ItemString$,s,255 
dim mstringf$Cnunberoffonts,6) 
for i=1 to numberoffonts 
toolbox GetItem,menuhandle(C4), i, ItemStr ing$ 
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toolbox GetFNum, ItemStr ing$, varptr(fontNum) 

toolbox RealFont, fontNum,size(1),sizestatus 

if sizestatus then mstring$Ci, 1) ="9 Point«0" 
nstring$Ci, 122"9 Point" 

toolbox RealFont, fontNum,size(2),sizestatus 

if sizestatus then mstring$Ci,2)="18 Point«0" 
nstring$Ci,222" 10 Point" 

toolbox RealFont, fontNum,size(3),sizestatus 

if sizestatus then mstring$Ci,322"12 Point«0" 
mstring$Ci,3)="12 Point" 

toolbox RealFont, fontNum,size(4),sizestatus 

if sizestatus then mstring$Ci,4)="14 Point«0" 
nstring$Ci,42s"14 Point" 

toolbox RealFont, fontNum,size(5),sizestatus 

if sizestatus then mstring$Ci,522"18 Point<0" 
mstring$Ci,522"18 Point" 

toolbox RealFont, fontNum,size(6),sizestatus 

if sizestatus then mstring$Ci,6)="24 Point<0" 
mstring$Ci,6)="24 Point" 


next i 
MenuItem = 1 ! default Menultem is 1 
for i= 1 to 4 


Iput items in menubar 

toolbox InsertMenu, menuhandleCi),@ 
next i 
gosub makesizemenu 
toolbox DrawMenuBar 

Idrew menu bar 
toolbox CheckItem,menuhandle(4), 1, true 
toolbox CheckItem,menuhandleC5), 1, true 
return 


makes izemenu: 
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else 


else 


else 


else 


else 


else 


toolbox NewMenu,5,pstr("Size" ), menuhandle(5) 
!create size menu 

toolbox AppendMenu, menuhandle(5), & 
pstr(mstr ing$(Menul tem, 1) 

toolbox AppendMenu, menuhandle(5), & 
pstr(mstr ing$(Menul tem, 2)) 

toolbox AppendMenu, menuhandle(5), & 
pstr(mstr ing$(Menul tem, 3)) 

toolbox AppendMenu, menuhandle(5), & 
pstr(mstr ing$(Menul tem, 4)) 

toolbox AppendMenu, menuhandle(5), & 
pstr(mstr ing$(Menul tem,5)) 

toolbox AppendMenu, menuhandle(5), & 
pstr(mstr ing$(Menul tem,6)) 

toolbox InsertMenu, menuhandle(5),9 
return 


A few words about Clear Lake Research Libraries with 
MS BASIC: CLR Libraries have been checked out on a 
Macintosh plus and worked with no problems. If you are 
having problems, check to see that your program is opening 
up the correct library name and that BASIC is in the same 
folder as the CLR Library. For that matter, your BASIC 
programs need to be in the same folder. The problems appear 
to be because of incompatibility between MS BASIC and 
HFS. 
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Add Three New Libraries to your CLR ToolLib 


Hello!! This month MacTutor features three new MS 
BASIC libraries to add to your CLR ToolLib collection. 
These routines were written by Clear Lake Research for use on 
future versions of BASIC library disks. To make it easy to 
add them to your ToolLib Libraries, we are providing a 
Statement adder program to write the hex codes directly to your 
disk. It will require that you already have CLR ToolLib in 
order to run the Statement Adder program as the resource 
routines are used to save the new libraries. 

The new libraries are: RealFont, KbEquiv and 
setItemStyle. RealFont is a Macintosh Font Manager function 
that returns TRUE if the font having the font number 
fontNum is available in the given size in a resource file, or 
returns FALSE if the font has to be scaled to that size. The 
syntax to call the CLR Realfont library is: 

Realfont fontNum%,size%, boolean 


The following example shows the use of RealFont: 
LIBRARY "NewL ibrar ies" 

fontNum%=4 ‘Monaco font 

size%= 18 

boo lean%=0 

RealFont fontNum$,size£$,boolean$ 

PRINT boolean$ 


Each font type is represented by a different font number, 
in this case a four represents the Monaco font. The size we 
are checking is 18. If size 18 exists in the Monaco font the 
the variable boolean% returns a TRUE, otherwise if the font 
does not exist in size 18 then a FALSE is returned. This 
routine is useful to create menus which include the size of 
fonts to be used by your program. Some font numbers can be 
found on page 290 of your MS BASIC manual. 

KbEquiv may be used to add keyboard equivalents to 
your menus. MS BASIC menus do no provide a way to add 
keyboard equivalents to your menus. An alternative is to trap 
all keyboard input and branch to the appropriate subroutine, 
but that is would require a separate routine which is not 
associated with the menu error trapping. Usually, calls to the 
menu manager would indicate which keys are to be used as 
keyboard equivalents to the menus. However, MS BASIC did 
not provide a way to use equivalent keys. The syntax for the 
KbEquiv statement is: 

KbEquiv Menunumber$, i tennumber , key$ 
where Menunumber% is the menu and itemnumber% is the 
menu item where the key will be added. The variable key$ is 
the one character key which will be used as the equivalent key. 
The routine implementation is shown in the Menu Styles 
Demo later in this article. 

A warning: The KbEquiv routine does not yet check if 
the menu indicated actually exists. Therefore be sure that you 
know your menu has already been created before calling this 
routine. Unpredictable results will occur. The future released 
version of this routine from CLR will check for the menu 
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before setting up the keyboard equivalent. 

The third routine, setItemStyle, is also a member of 
the Menu Manager routines. SetItemStyle changes the 
character style of the given menu item to the indicated 
character style. The syntax is: 

setItenStyle Menunumber$, itemnumberZ, stylef 
where menunumber% is the number of the menu and 
itemnumber% is the number of the item in that menu. 
Style% is an integer number representing the style of the 
menu item. Style% is the same as the values used to 
represent the attributes of the TEXTFACE statement. The bit 
for each attribute is listed on page 291 of your MS BASIC 
manual. (Example: bold, shadow has a value of 17; Italic and 
underlined has a value of 12). The Menu Styles Demo 
demonstrates how to set up your own style menu. 

To install your new libraries run the statement adder 
program listed below. The KbEquiv, Real Font and 
setItemStyle routines will be added to a new file named 
NewLibraries. This newly created file will be a CLR library 
file but without the LibInit function; just the three new 
statements we've added this month. Next you will need to run 
the Statement Mover program which is provided with the 
CLR Libraries disk. Statement Mover is a handy BASIC 
program which will copy libraries from one file to another. In 
fact, I recommend that you copy the libraries that you are 
using to your BASIC program file (i. e. add the library 
resource to your BASIC program). The BASIC program is 
stored in the data fork of the file, and the resource fork will 
then contain the libraries used by the program. Use Satement 
Mover to copy the LibInit routine to the NewLibraries file! 
LibInit is needed by BASIC to be sure that the Library file is 
a MS BASIC Library. LibInit must be in the same file as 
each of the libraries that you use. Of course if you choose to 
move the NewLibaries file into your already existing ToolLib 
file, then you don't need the extra LibInit function. In fact, if 
you can spare the space, you might want to merge all the 
library routines into a single ToolLib file using the Statement 
Mover program. Here is a review list of everything CLR has 
published: 


CLR LIBRARIES 
ToolLib Original CLR ROM Interface 
SpeechLib Speech stuff for MacinTalk 
MathStatLib Math and Statistics routines 
NewLibraries Output of this month's program 


The ToolLib and MathStatLib are available on the CLR 
Utilities Disk from the MacTutor Mail Order Store for $50. 
The SpeechLib is available seperately on the CLR Speech disk 
for $20. We tried to encourage CLR to combine the two 
products to avoid customer confusion, but they were unable to 
do so. 
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The Menu Styles Demo will try to open the 
NewLibraries file, so you should be sure that LibInit is moved 
to the New Libraries file or that the program calls the name of 
the Library containing the setltemStyle and KbEquiv routines 


(RealFont is not used in the demo). 
‘Statement Adder 


*" for RealFont, KbEquiv, and setItemStyle libraries 


‘By Clear Lake Research and David Kelly 
'€ Clear Lake Research, Inc. 
‘used with permission 


‘NOTE: The hex codes for RealFont, KbEquiv, setI temStyle 


‘are copyrighted by Clear Lake Research. 


‘By using Statement Adder you may create these libraries 


‘then add them to your ToolLib Libraries using 
‘Statement Mover (provided with CLR ToolLib). 


‘This program requires ToolLib and MS Basic 2.0 or 2.1 


‘Run this program only once. 


LIBRARY" Too 1L ib" 
DIM p&( 120) 


REM read hex code 
READ nm$ 
READ id$ 
READ numofbytes% 
DIM pX(nunofbytest) 
FOR i$- 1 TO numofbytess 
READ p%(i%) 
NEXT i$ 
f ileRefNun$-0:H!-9 
openResF i le"NewL ibraries",f ileRefNum% 


as type GNRL' 
GetNamedRes fileRefNumZ, "GNRL", nm$,H! 


'openResF ile 
saveArray f ileRefNun$,p$C1),numofbytes$*2, id’, nn$ 


“save 


‘get resource 


detachRes H! "Now it 
is not a resource 

AddRes fileRefNum%,H!, "CODE", id%,nm$ "type CODE 

releaseRes H! 

GetNamedRes f ileRefNum$, "GNRL",nm$,H! "Not needed 


removeRes fileRefNum$,H! 
‘so remove it 


REM early printings of the manual had the syntax of 
REM removeRes wrong. The first argument was left off. 


CloseResFile fileRefNum% 


REM make sure libinit is in the file before running it! 


NEXT j 
PRINT"Done" 


‘do next of three functions 
‘end of program. 


‘setI temStyle Library 

DATA "setItemStyle" :REM name of resource nm$ 
DATA 5001: REM id number idg 

DATA 33: REM number of bytes 

DATA &H8, &HO, &H4EAD, &H2A , &HCOO 

DATA &H3,&H662C, &HSA 12, &H5245, &H4EAD 
DATA &H2A , &HCOO , &H3, &H66 1E , &H36 12 

DATA &H4EAD, &H2A, &HCØØ , &H3 , &H66 12 

DATA &H38 12, &H42A7 , &H3F05 , $HA949, &H3F03 
DATA &H3FO4 , &HA942, &H7000 , &HAET5, &H740D 
DATA &H7000, &HAEAD, &H42 


'RealFont Library 

DATA "RealFont": REM name of resource nn$ 
DATA 703: REM id number id$ 

DATA 37: REM number of bytes 

DATA &H8, &HO, &H4EAD, &H2A , &HCOO 

DATA &H3, &H6632, &H38 12, &H4EAD , &H2A 

DATA &HC00,&H3, &H6626, &H3A 12, &H4EAD 
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DATA &H2A,&HC40 ,&H3,&H66 1A, &H4267 

DATA &H3F04, &H3FO5, &HAO02 ,&H30 IF ,&H6708 
DATA &H34BC, &HFFFF , &H7000 , &H4E75, &H4252 
DATA &H7000, &H4E75, &H7000, &H303C, &HD 
DATA &H4EAD, &H42 


‘KbEquiv Library 

DATA "KbEquiv":REM name of resource nm$ 
DATA 191:REM id number id$ 

DATA 58: REM number of bytes 

DATA &HØ,&H1,&H4EAD , &H2A , &HCOO 

DATA &H3,&H665E , &H38 12, &H5244 , &HAEAD 
DATA &H2A,&HCOO , &H3, &H6650 , &H3A 12 

DATA &H4EAD, &H2A, &HCØØ , &H2 , &H6644 

DATA &H264A, &HAEAD, &H82 , &H4EAD, &H8A 
DATA &H 16 13, &H42AT , &H3F04 , &HA949 , &H2657 
DATA &H2653, &H303C, &HE , &H 1233, &HÓ 

DATA &H524 1, &HDO4 1, &H5345 , &H6008 , &H 1233 
DATA &H2 ,&H5A4 1, &HD241, &H5 ICD, &HFFF6 
DATA &H1233, &HO, &H544 1, &HD04 1,&H 1783 
DATA &HO, &HA948 , &H7000 , &H4E75, &H740D 
DATA &H7000, &H4EAD, &H42 


'Menu Styles Demo 

"@MacTutor 1986 

‘by Dave Kelly 

‘With special thanks to Clear Lake Research 
‘for allowing use of KbEquiv, RealFont, 
‘and setItemStyle Libraries 


LIBRARY"NewL ibrar ies" 
TEXTMODE 1 

DIM st%( 10) 

MENU 6,9,1,"Style" 


MENU 6, 1, 1, "Plain" 

MENU 6,2, 1, "Bold" 

MENU 6,3, 1, "Italic" 

MENU 6,4, 1, "Underline" 

MENU 6,5, 1, "Outline" 

MENU 6,6, 1, "Shadow" 

MENU 6,7, 1, "Condensed" 

MENU 6,8, 1, "Extended" 

MENU 6,9,9,"-" 

MENU 6,10, 1, "Quit" 

FOR if =Ø TO 6 
$t8Ci8+2)=2° if 

NEXT if 

‘Variable Value Attribute 

j st£C1) ø Plain Text 

' st%(2) 1 Bold 

i st%(3) 2 Italic 

i st%(4) 4 Under ined 

l st8(5) 8 Outlined 
st2(6) 16 Shadow 

' st%(7) 32 Condensed 

‘Cless space between characters) 
st%(8) Extended 


‘(more space between characters) 


‘Set up menu styles 
FOR iZ= 2 TO 8 
setItemStyle 6, i%,st%CiZ) 
st$(i2)-0 
NEXT i$ 


‘Set up keyboard equivalents 
FOR i$ = 1 T06 
READ A$ 
KbEquiv 6, iZ A$ 
NEXT if 
KbEquiv 6, 10, "Q" 
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DATA P,B,1,U,0,S 


ON MENU GOSUB MenuEvent 
MOVETO 12,50 

PRINT "Hello World!" 
Style%=0 

MENU ON 

loop: 

GOTO loop 


MenuEvent: 

menunumber 3=MENUC@ ) : menu i temZ=MENUC 1) : MENU 
IF menunumber%=6 THEN ItemEvent 

RETURN 


ItemEvent: 
ON menuitem% GOSUB plain, bold, Italic, Underlined, 
Outlined, Shadow, Condensed, Extended,, quit 


plain: 

Style%=6 

MENU 6, 1,2 

FOR i%=2 TO 8 
MENU 6,i$,1 
st$(122-0 

NEXT i$ 

GOSUB printscreen 

RETURN 


printscreen: 
TEXTFACE Style% 


CLS 

MOVETO 10,50 

PRINT "Hello, World!" 
RETURN 


bold: 
IF st8(2)= THEN st%(2)=1 ELSE st%(2)=0 
IF st£(2)-0 THEN MENU 6,2,1 ELSE MENU 6,2,2 


Computestyle: 
MENU 


StyleZ=Styleftst%¢ if) 
NEXT if 
GOSUB printscreen 
RETURN 


Italic: 

IF st%(3)=0 THEN st%(3)=2 ELSE st%(3)=0 

IF st&(3)=0 THEN MENU 6,3, 1 ELSE MENU 6,3,2 
GOTO Computestyle 


Under ined: 

IF st%(4)=0 THEN st%(4)=4 ELSE st%(4)=0 

IF st%(4)=0 THEN MENU 6,4, 1 ELSE MENU 6,4,2 
GOTO Computestyle 


Outlined: 

IF st%(5)=0 THEN st%(5)=8 ELSE st%(5)=0 

IF st2(52-0 THEN MENU 6,5, 1 ELSE MENU 6,5,2 
GOTO Computestyle 


Shadow : 

IF st%(6)=0 THEN st$C62-16 ELSE st%(6)=0 

IF st%(6)=6 THEN MENU 6,6, 1 ELSE MENU 6,6,2 
GOTO Computestyle 


Condensed: 
IF st%(7)=8 THEN st%(7)=32 ELSE st%(7)=0 
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IF st%(7)=0 THEN MENU 6,7, 1 ELSE MENU 6,7,2 
GOTO Computestyle 


Extended: 

IF st%(8)=0 THEN st%(8)=64 ELSE st%(8)=0 

IF st%(8)=0 THEN MENU 6,8, 1 ELSE MENU 6,8,2 
GOTO Computestyle 


Using HFS with MS BASIC and other applications 


The release of the Apple Macintosh plus has created a few 


compatability problems for MS BASIC users. It is rumored 
that Microsoft is in the process of fixing MS BASIC so that 
it will be completely compatable with HFS. The following 
tips may help in getting around some of the problems until a 
more permanent solution is released (i.e. a new verison of MS 
BASIC). 


Problem: MS BASIC can't find files in 
folders. 

Solution: | Use the HFS.FIX program by Andy 
Hertfeld. It will add a resource to your system to help 
search through folders to find the files you want. This 
will work in 95% of the cases. In some cases BASIC 
must be in the root volume with the application. This is 
true for use of some CLR Libraries. We have not found 
any CLR routines that do not work with HFS. The 
problems that exist are related to the BASIC interpreter, 
not the Libraries. If you suspect a problem, try placing 
Basic, the application file and the libraries it uses in the 
root directory for that disk; ie not in any folder. Another 
solution would be to use MFS formated disks for your 
BASIC programming. This is NOT the preferred 
solution, however, it will be sure to work. 

Notes on using the RAM Cache with any software: I 
recommend that you NEVER change the cache from 
within any application. Since most software doesn't keep 
track of the cache, it can cause some catastrophic results. 
When using Switcher, be sure to turn off the cache 
completely. Switcher may allocate the same memory 
that the cache is using (without knowing it); the memory 
contention will surely cause a disaster. On the Mac Plus 
there is 850278 bytes of free space left in MS BASIC's 
data segment with the cache turned off. With a 128K 
cache on there is still 719214 bytes left. I have not seen 
any problems in using the cache with BASIC. In fact, 
your program will run much faster with the cache on. 
The size of the cache is arbitrary. 

Initializing single sided disks as double sided 800K disks: 
We take no responsibility if you lose any data when 
using single sided disks as double sided, however, those 
that have been re-initializing their 400K disks have not 
had any noticeable problems with any of them. The 
differance between single and double sided disks: The side 
that you use is polished and has been verified before 
shipping. Typically, both single and double sided disks 
are manufactured the same way, only the QA checks and 
certification are missing, meaning you can usually get 


away with it. Al 
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Alerts and MS Basic 

Let's talk about how to set up your own Alerts. For any 
of you that are not sure what alerts are, just pull down the 
‘About’ menu from just about any application. The dialog box 
in an 'About' menu item is a form of an alert that usually 
gives information about who wrote the application. For 
Macintosh programmers who are experienced in C or Pascal or 
other languages with Toolbox access, Alerts are probably old 
hat. MS BASIC programs have traditionally been using one 
of four regular windows for Alerts with the simulated Alert 
itself being controlled by programming within the BASIC 
program instead of by the Toolbox. 

User Modified Programs 

One feature not found on other computers is the ability to 
modify or customize the text, menus etc. after the program is 
written. This ability is only found in programs that use 
resources to store the menu, window, dialog or alert 
information. Therefore, since you must set up the 
information inside the BASIC program when using MS Basic, 

you must rewrite that section of BASIC code in order to 
change the information. For example, to change a menu from 
English to French would require that you translate each 
MENU command to French and modify each program line. 
Thats not too hard to do, and not necessary very often, but 
still a disadvantage over other Mac languages. 

How many times have you tried to figure out what size 
window you need in your program and have to guess at what 
the window coordinates are on the screen and then guess where 
the controls will be inside the window? What a pain. I tried 
to help out several issues of MacTutor back with the 
Rectangle Sizer program. That was ok, but you still had to 
use some trial and error till you got everything to look just 
right. The elegant solution is not to try to create your own 
custom windows in BASIC, but to create custom Alerts which 
may be used as often as desired, created much easier using 
ResEdit. (For a good discussion of Resource Editors, see Joel 
West's column in the May, 1986 MacTutor.) 

CLR ToolLib Gives Access to Alert Resources 

MS BASIC alone still has the limitation of having to set 
up Alerts as windows and simulate Alerts in the windows 
from Basic. Using the CLR ToolLib, Alerts are called as 
easily in BASIC as they are in other Toolbox Languages (C, 
Pascal, etc). Any language which has access to the Toolbox 
commands can use this column to help them understand Alerts 
better. 

Alerts are probably one of the simplest routines to use. 

In most programs, you have to process the event in order to 
tell what selections are made. This is true when you set up 
your own dialogs (as you must do with MS BASIC). By 
using Alerts, you let the Toolbox ROM do part of the work 
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IOS 
MacTutor Alerts 


ResEdit Creates Staged Alerts for Basic 


Dave Kelly 
Editorial Board 


for you. The toolbox automatically tracks the movement of 
the mouse for you and checks to see what controls or edit 
fields have been accessed. 

There are three major kinds of Dialogs: 


(1) Alerts 
(2) Modal Dialogs 
(3) Modeless Dialogs 


The lowest level is Alerts, normally used to display error 
messages or other information. The Alert is always front- 
most on the screen and the only action which is allowed, takes 
place in the dialog box. The next level of dialogs are called 
modal dialogs’. In this 'mode', the dialog box will respond to 
the mouse and the keyboard. The modal dialog also remains 
frontmost on the screen and the user may dismiss the dialog 
with the keyboard or the mouse. 'Modeless dialogs’ are dialogs 
which the user may move around on the screen, has a go-away 
box, and the user can activate other windows (bring to the 
front). This is the mode supported by MS BASIC except that 
MS BASIC can't save a set dialog as a resource for repeated 
use. Instead you have to dedicate one of MS BASIC's four 
windows (only four windows may be open at one time) to be 
the desired dialog. [Note: ResEdit is available on the Utilities 
Disk. See the MacTutor mail order store for information. -Ed.] 

How to Use ResEdit 

Before we get into how to call the Alerts using CLR 
Libraries and MS BASIC, let's set up our own custom Alert 
file using ResEdit. ResEdit is considered the easiest way to 
Set up your own Alert resources. Here's what you do: 

Start up ResEdit and either open a current file (the one 
you want to store your alert in) or open a new file. To open a 
new file, select NEW from the File menu. 

When selecting a new file, you must supply a filename 
for your file (In the example, the filename is 'MacTutor 
Alerts). Next select New to create a new resource in the 
newly created file. Enter the new Type Name which is the 
name of the type of resource to be created (see figure 1). In 
this case we will choose ALRT to create an Alert resource. 
ResEdit automatically assigns an unused ID number for the 
Alert. We will use the default in this case which is 2252 
(your default ID number will probably be different). After 
selecting OK, then select NEW from the File menu. A 
window like that in figure 2 will appear and you can now 
graphically adjust the position of the Alert box by dragging it 
around in the window. You may want to wait till the Alert is 
complete to adjust the final position. The Alert box can be 
stretched by pointing the mouse about 1/8 inch from the 
bottom right corner (inside the Alert box) and dragging the 
corner out to the correct size. 
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Figure 1 


Next toggle the graphics to text by selecting the ALRT 
menu. Figure 3 allows you to see the actual screen 
coordinates where the Alert will appear. You can edit these 
from here by changing top, bottom, left or right. ResID is 
the DITL (Dialog ITem List) id number. Every alert has an 
Dialog Item list associated with it which gives information 
about what is in the Alert. We will create our own DITL 
resource in a few moments. 


Alert ID = 2252 from MacTutor Aler 
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Figure 2 

The remainder of the window shown in Figure 3 involves 
staged Alerts. This means that your alerts can be staged to 
behave differently each time they occur. Up to 4 stages can be 
defined by selecting the ResEdit controls shown in figure 3. 
The '2 bold' button will cause item #2 to be the default item 
(the item shown in bold in the alert box which can be selected 
automatically with the return key). If not selected then item 
#1 will be the default (bold) item. The 'drawn' button 
indicates if the alert will be drawn. If the 'drawn' button is 
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selected in stage 1 and not in stage 2, the alert will be drawn 
the first time it is called by the application program, but the 
second time called the alert would not be drawn. The sound is 
a number from O to 3 indicating the number of beeps to sound 


Alert ID = 2252 from MacTutor Aler 
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ResID o | 


sound 


stage 1 []2 bold [| drawn O | 
stage 2 []2 bold (| drawn UN 
stage 3 []2 bold [] drawn 0 | 
stage 4 []2 bold [] drawn 0 


Figure 3 


when the alert is selected. There is also a way to call your 
own sound routine, but that subject will not be covered here. 
You can experiment with values of sound (0-3) and run the 
demo program to see how it works (or write your own). 

You can also find out what stage the last alert is currently 
up to by using the system global called ACount located at 
&HA9B. You may reset the alert to the first stage by using 
the system global ACount (use POKE  &HA9B, 
&HFF:POKE &HA9A,&HFF to reset to O ). The resource 
ID of the last alert is found in the system variable ANumber. 
Use PEEK(&HA9A)'256)-PEEK(&HAO9B) to display 
ANumber. It appears from the demo program included with 
this column that ANumber doesn't get incremented when the 
4th stage is used. ANumber remains a three after the 3rd 
stage. That's ok, because all subsequent use of the alert will 
result in the 4th stage condition anyway. 

The DITL Resource 

To create the DITL resource, close the Alert resource 
windows back to the MacTutor Alerts window (i. e. leave your 
file open, but you may want to save what you have done so 
far by closing the file window also). Now with the MacTutor 
Alerts window open we again select a new resource by 
selecting NEW from the File menu. You should see the 
window of figure 4. Just like the way we created the ALRT 
resource, select the New Type Name of DITL and select OK. 

Now you are ready to create each item of the Dialog 
ITem List (DITL) resource. Select New to create a new 
dialog item. An Edit Item window will appear similar to the 
one in figure 5 (figure 5 is for item #4, our first item will be 
item 41). Item 41 will be the item to be used as the default 
(shown in bold when the Alert is displayed) unless Item #2 is 
selected when setting up the Alert stages, in which case Item 
#2 will be displayed in bold. Items can be buttons, icons, or 
pictures. They could also be a special User item which I 
won't discuss here. Enabled and Disabled refers to whether or 
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not you will be able to dismiss the Alert box by selecting the 
indicated item. You can change the item location from this 
window, but by simply closing the window you will see the 
item appear with grabbers for resizing the item. Note that you 
may choose to have a picture default to its original picture size 
to maintain the integrity of the picture from the menu. 


MacTutor Alerts 


Figure 4 


Using Pictures or Icons 

To use pictures or icons you should enter the Resource 
ID (as in figure 5) for the Picture or Icon resource to be used. 
It is common to use the same ID for the picture as for the 
alert, but you don't have to. Just in case you don't have a 
picture resource available, one can be created very easily. 
CLR ToolLib comes with a Scrapbook mover utility which 
will convert pictures stored in the Scrapbook to PICT files. 
To use it you may use an existing file or you can create one. 
You may create one by selecting (similar to what we did back 
in figure 4) the PICT file type as shown in figure 6. 

At this point you can use the Scrapbook Mover (from 
CLR) to move a picture into the PICT resource. You may 
already have a PICT resource already that you wish to use. 
After you have set up your PICT resource with ture you 


E Edit item ? 4 ESEESEESE— 


© Button 
Q Check bou 
Q Radio control 


© Static tent 
© Editable text 


© CNIL resource 
© ICON resource 


@ Enabled 
© Disabled 


top 


en 6 
bottom 


right 


@® PICT resource 
© User item 


Figure 5 
will use, choose Get Info and change the PICT ID# to the 
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same as the alert we will be using as in figure 7. The 
important thing is that the ID# in the DITL resource 
cooresponds to the ID# of the PICT resource to be used. In 
our demo program we have two of our favorite PICTures in 
our PICT resource. You will have to provide your own or 
else use the MacTutor source code disk to use our own PICT 
resource. Be sure to change the ID numbers in the basic 
program to match your resources. 

Back to the DITL resource for a moment.  ResEdit 
provides the ability to customize your Alerts graphically. 
You can move each item around to suit the application you are 
programming. Figure 8 shows the Dialog item list for one of 
our sample Alerts (used in the demo basic program). 

Another item worth mentioning is that in Alerts that 


Figure 6 


contain only a picture, the picture should be the 2nd item or it 
will be set in bold as the default item. You can either create a 
dummy unselectable text field as item #1 or you can set the 
default item to item#2 by changing the staging setup (as in 
figure 3). You could hide a dialog item by moving it outside 
of the dialog window range. In figure 9 the cursor is pointing 
at item 41 which can be hidden from view by going to the 
Dialog Item List (DITL) and enlarging the window and then 
dragging the item to a location outside of the dialog window 
size. Figure 10 shows the Alert box with item#1 hidden 
outside of the window. 

Figure 12 shows the final Alert resource as displayed 
graphically with ResEdit (See next page). Your custom dialog 
will be different than this of course. 

One more thing in conclusion: Select Get Info for the 
ALRT resource and set the Preload and Purgeable buttons. 
Preload forces the entire Alert (PICT / ICON, DITL and 
ALRT resources to allocate memory and be loaded into the 
heap. The purgeable button lets the alert Occupy memory 
until some other resource needs the memory. The Alert will 
be copied from the disk when it is first needed and as long as 
memory is not required for something else, it may be reused if 
desired. Resources are accessed from MSBASIC with the 
CLR command: Alert _ fileRefNum%,type%,id%, item%. 
Instructions for its use are clearly identified on page 40 of the 
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Info for PICT 2252 from MacTutor Alerts ES 


Type: PICT Size: 889 


ID: 2252k —— Owner type 


2 


l WDEF | | 


L] Locked 
C] Protected 


fittributes: 
L] System Heap 
[ ] Purgeable 


L] Preload 


Figure 7 


Dialog item list ID = 2252 from MacTu 


Figure 8 


CLR libraries manual. [Note: The CLR ToolLib is available 
from the MacTutor Mail Order Store. -Ed.] Setting the Preload 
and Purgeable buttons is shown below in figure 11. 
Alert Demo Program 
The following MS Basic program demonstrates how 
Basic, using the CLR ToolLib library, can access a resource 


Alert ID = 12696 from MacTutor Ale 


MacTutor 


Tip Macintosh Programmi Joarmd 


ES 


Figure 9 


file and display an alert. This program opens the ToolLib 
library file, and the 'MacTutor Alerts’ file of resources that we 
just created using the ResEdit program. Both the ToolLib file 
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Alert ID = 12696 from MacTutor Ale 


MacTutor 


The Müacintcsh Progamming Joal 


Figure 10 
and the resource file 'MacTutor Alerts’ must be in the same 
folder as MS Basic as the program below is written. If you 
want either file in another folder, you must specify the 
complete path file name so the files can be found. Otherwise, 
Basic defaults the path name to the folder where it found the 
Basic interpreter. 

The first alert is the MacTutor icon box with the three 
choices about reading MacTutor. The ID number for this alert 
is 2252. When we start this alert by calling the subroutine 
'doalert', that subroutine actually calls the alert four times. 
This gives the user an opportunity to click on all three boxes. 
After each alert, we print the information on the staging status 
and which button was pressed. 

The second alert, ID 12696, displays the MacTutor 


Info for ALRT 2252 from 
Type: RLRT Size: 12 


ID: 2252 | owner type 


WDEF | | 


Sub ID: 


NENNEN MDEF E» 


Rttributes: 


[]System Heap 
em 


[]Locked 
C Protected 


J Preload 


Figure 11 
magazine header, and again, through our 'doalert' subroutine, 
gets called four times. Each time, the stage of the alert 
increases, as does the number of beeps. After the fourth call, 
the alert is finished and the program ends. 


' Staged Alerts 
'eMacTutor 1986 
' by Dave Kelly 
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Alert ID = 2252 from MacTutor Aler ,2252 


* No format specification available. 


, 12696 
* No format specification available. 
, 15941 
* No format specification available. 
, 11658 
* No format specification available. 
Type DITL 
» 2202 
* 1 


BtnItem Enabled 
16 184 40 264 
Yup! 


Figure 12: Our Final Alert Resource * 2 
BtnItem Enabled 
56 184 80 264 


Yes 
WINDOMI, "Alert Staging Demo", (2,40)-(510,340) 
LIBRARY "ToolLib" x 3 
f i leRefNum&=0: i tem%=0 BtnI tem Enabled 
OpenResFile "MacTutor Alerts", f ileRefNumg 96 184 129 264 
' Here comes the first Alert Absolutely 
1d$22252 
POKE &HA9B,&HFF:POKE &HA9A,&HFF ‘Set stage to Ø X 4 
GOSUB doalert PicItem Disabled 
' Here comes the second Alert 40 56 116 120 
id%= 12696 2252 
POKE &HAQB, &HFF : POKE &HASA,&HFF ‘Set stage to Ø 
GOSUB doalert * 5 
‘All done with this alert business! StatText Disabled 
CloseResFile fileRefNumg 16 8 39 668 j 
LIBRARY CLOSE Do you read MacTutor? 

12696 

doalert: 2 ^"! 
Alert fileRefNumZ, 0, id$, items * l 
GOSUB printit BtnItem Enabled 
Alert fileRefNun$,0, id$, items 208 225 222 263 
GOSUB printit 
Alert fileRefNumn$,0, id$, items x 2 
GOSUB printit PicItem Enabled 
Alert fileRefNum$,0, id%, items 25 21 139 443 
G0SUB printit 12696 
RETURN 
printit: Type ALRT 
TEXTFONT C42:TEXTSIZE (12) 
LOCATE 15,1 ,2252 (36) 
PRINT "Alert ID#" ; CPEEKC&HA982*256 )+PEEK(&HAQ9) 72 126 210 410 
PRINT "ITEM*";item$;" was selected." 2252 
PRINT "Stage *"; CPEEKC&HA9A 24256) *PEEKCLHAOB F6D4 
RETURN 


, 12696 (36) 


68 20 234 490 
REdit Decompiles Resources 12696 


The following file is a partial disassembly of 'MacTutor | 7654 
Alerts' file using REdit, the European resource editor. REdit 
can decompile resource files created by ResEdit into a text file 
for documentation purposes. Unfortunately, it is not complete 
as the PICT resources are not de-compiled. [REdit is also 
available on the Utilities Disk. -Ed.] 


MacTutor Alerts.rsrc 


Type PICT 
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Special Projects 


DB Cooper 


[z-3 
EN Seattle, WA 


Recovering Protected Basic Programs 


True Recovery at Last! 


How many times have you saved what you thought was a 
completed MS Basic program to disk in protected mode, only 
to discover that was your only copy and now you need to 
make some changes? Recovering from Basic's protected option 
has been a hotly contested struggle between Basic 
programmers and the interpreter, which until now, has yielded 
very little in the way of a practical solution. In past issues of 
MacTutor, various attempts have been published, but each of 
these required that you do something to your program before 
you protected it. What if you didn't remember to do the special 
thing first? You were out of luck. Until now. After studying 
Mike Steiner's "Rescuit Program" in the September 1985 
issue of MacTutor, I have invented a way to recover any 
protected Basic program after it is protected without any 
requirement on the author before he saved it. In otherwords, 
you can now unprotect any protected program without 
thinking about it ahead of time. Simply run this Basic 
program and your back in business! I accomplished this by 
writing the program below named ‘Rescure(b)', which 
overwrites the encrypted code for: (Merge "it":') at the front of 
the protected program. Then I set up a second program named 
Tt which is merged to the protected program and then copies 
the program from memory to a file. This second step is based 
on Mike Steiner's article. 

Version 2.1 Different 

Unfortunately, this scheme didn't work with programs in 
the Microsoft Basic 2.1 Format, so I started to experiment. I 
determined that version 2.1 uses a seperate location in memory 
to store the names of the variables. I couldn't figure out how 
to find this table in memory directly, so instead I added a new 
variable "TenZZZZZZZZZZ" to the end of the table by 
defining it in the program, and had the routine search for ten 
Z's in a row. Then the program back tracks until it hits a 
binary zero, which defines the beginning and end of the 
variables table. (This method has worked with all the 
programs I have rescued, but I wouldn't bank on it always 
being successful.) 

Cleaning up Garbage 

At this point I ran into still another problem. The rescued 
program list still showed garbage in the variable and label 
names about 5096 of the time. I scratched my head some more 
before I finally realized that the main listing must end with an 
odd number of characters (or even, when the first character is 
removed after the program has been loaded). I put in a counter 
to check for oddness. 

After this final fix, the program seems to run quite well. 
When a rescue is completed, the rescued program must then be 
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saved at once by the operator or the program rescued will not 
show the proper icon and the list window may show garbage 
when entered from the Desktop. (I still don't know the reason 
for the latter. ) At any rate, when 'Rescue(b)' has run, it leaves 
the rescued program loaded in memory, so you can simply do 
a "Save As" and your program will be fully recovered. 

Ideas on the Encryption Used 

The encryption method involves three steps; First, the 
binary value from each field is added to an offset in the range 0 
to 255. If the sum is greater than 255, then 256 is subtracted 
SO as to be in the proper range. Next, a mask in the same 
range is operated on the value using the logical XOR operand. 
Finally a second, different offset is subtracted from the result. 
The final binary code is truncated to the proper range and 
written to the file. (Note that, properly written, the same 
routine can be used to encode and decode the binary data.) Each 
position has its own offsets and masks which are calculated in 
some manner I couldn't determine, but these parameters are 
always the same at a given position, regardless of the program 
encrypted. 

Since (Merge "It":'} is overwritten at the beginning of 
the file being rescued, it is best to use a copy of the same for 
the rescue. I added a separate, temporary file to store the values 
that were overwritten. These are later restored by the 
subroutine "Rescue" and the result is saved with the program 
code in the file: filename.IMOK'. 

Using Rescue(b) 

The programs work with files saved in both version 2.0 
and 2.1 but must be run under the same version of BASIC. 
Files in version 2.0 are not saved properly when run under 
version 2.1 and presumably version 2.0 will not load version 
2.1 files. If you have protected version 2.0 programs and don't 
have a backup of BASIC version 2.0, you're out of luck! 

The program 'Rescue(b)' as listed below will rescue any 
Binary Basic programs. To rescue Decimal programs, change 
the 'MSBC' to 'MSBB' where indicated in the source code and 
save the modified Rescue program as a Decimal program file 
(ie: 'Rescue(d)'.) The second program listed below, called 'It', 
need only be written once and saved as a text file, but it must 
have the name "It" and both the ‘Rescue’ program and the 'It' 
program must reside on the default disk that has the Basic 
interpreter on it. 

To use the program, make a copy of a Basic program and 
save it in protected mode. Then run the program 'Rescue(b)'. A 
standard file dialog box will come up and ask for the name of 
your protected program. Then the selected program will be 
loaded into memory, the 'It' text program will be read in and 
merged to the protected program, and the de-protection will 
take place (allow a minute or two for this, nothing will 
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happen on the screen yet.) When done, another dialog box will 
come up indicating the process is done. At this point, the 
unprotected program will be in memory. Go to the File menu 
and do a "Save As" under a new file name, then quit Basic and 
try running and listing your new program. It should both run 
and list normally. 

Well, that's about it. I have successfully rescued about a 
dozen different programs I previously protected, both Binary 
and Decimal, and in both version 2.0 and 2.1. It works 
properly on a skinny Mac, so presumably it will work on the 
bigger machines. The Program 'It' searches for the binary code 
for 'Merge "It":' in memory, so it shouldn't matter what size 
your Mac is. 

Too bad the folks at Microsoft didn't employ a Password 
scheme to allow program recovery, then all of this wouldn't 
have been necessary! As a precaution against disgruntled 
vendors, I am publishing this article under a pen name. Don't 
try to find me, as my name suggests, I'm gone! 


'<<< RESCUE PROTECTED MICROSOFT® BASIC FILES. 

'<<< This program must be run under the same BASIC 

'<<< type & version number as the f ile being recovered. 

««€ Keep the file named 'It' on the drive with besic. 

'<<< Open temporary file to store values 

OPEN "Garbage Bag" AS #1 LEN=174 

FIELD QU AS N$,2 AS 1$,4 AS T$,2 AS L$,36 AS K$,2 AS 
B 


WINDOW 1, ,(59,30)-(212,46),4 
CALL TEXTFONTCO) 
DIM Keep%( 18) 
"<<< Ask for protected Program to rescue. 
PRINT "Select a file to rescue..."; 
ID$-FILES$C 1, "MSBD") 
'<<< (Use "MSBP" instead for decimal program. ) 
IF ID$="" THEN SYSTEM 
WINDOW CLOSE 1 
OPEN ID$ AS #2 LEN-2 
FIELD 32,2 AS H$ 
'<<< Determine version and set type. 
'<<< Decode length field of first Program line. 
GET #2, 1: Type$="MSBC" 
PreS-VALC"&H"*LEFT$CHEX$CCVICH$22,22?*1 
IF Pre%=247 OR Pre%=251 THEN Type$="MSBB" 
RESTORE FirstLine 
GET #2,2 
Code%=VAL( "&H"+MID$ CRIGHT$ "8" +HEX$(CVICH$)), 4), 1,2)) 
READ Offset 1%, Mask, Of fset2% 
GOSUB Cryptor 
Keep2(0)-Bi teg 
'<<< Decode and store positions 5-22 of Program 
RESTORE OtherL ines 
TotalZ-Keep£$(02:12-2 
WHILE 18:29 
PlaceZ=INTC1%/2)+2 
GET #2,Place% 
Char$22*I$-4*Place$49 
CodeS=VALC"&H" +MID$CRIGHT$( "O" +HEX$(CVICH$)), 4), Char2,22) 
READ Offset 1%,Mask%, Of fset2% 
GOSUB Cryptor 
Keep%(I%-1)=Bite% 
IF 1%=Total% AND 1%<14 THEN Total&S=Total&+Bi te 
I$-I2*1 


WEND 
‘<<< Write coded (MERGE "It":' ) on Program 
RESTORE Modify 
FOR I%=1 TO 5 
READ Convert$ 
LSET H$-MKI$CConvert£) 
PUT #2, 1%+2 
NEXT If 
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"<<< Recode length of new first line 

"<<< Note Offsets are reversed for recoding 

RESTORE FirstLine:Code%=Totalg 

READ Of fset2%,Mask%, Offset 18 

GOSUB Cryptor 

GET 82,2: A$=RIGHT$( "00" +HEX$(CVICH$)), 4) 
MID$CA$, 1,2)=RIGHT$("O" +HEX$(Bi teZ), 2) 
LSET H$=MKI$CVALC"&H"+A$)) 
PUT #2,2 

CLOSE #2 

NAME ID$ AS ID$, "TEXT" 

'<««< Save old values to temporary file 
FOR I$-1 TO 18 

Kp$=Kp$+RIGHT$( "0" +HEX$(Keep%(1%)),2) 

NEXT If 


LSET N$=ID$ 
LSET I$=MKI$CLENCID$)) 
LSET T$=Type$ 
LSET L$-MKI$CKeepg(0)) 
LSET K$=Kp$ 
LSET B$-MKI$CPre2) 
PUT 51,1 
CLOSE #1 
'««« Print message, then chain to Program. 
'««« The file 'It' will then be merged to 
'<<< the end of the Program. 
WINDOW 1,,(160, 118)-(345, 174),2 
CALL TEXTFONTCO) 
PRINT "Now merging the file 'It' to" 
PRINT "'"+ID$+"'" 
PRINT "Please enter 'Rescue' in the" 
PRINT "Command Window..."; 
CHAIN ID$ 
'««« Routine to code/decode protected file 
Cryptor: 
Code%=Code%+0f f set 1%+256 
Code$-Code$-256* INT( Code% /256) 
Bite£-Code$ XOR Masks 
Bi teZ=Bi teZ-Of fset2%+256 
Bi te=B i teZ-256* INT(Bi te%/256) 
RETURN 


FirstLine: 
DATA 118,27,244 
OtherL ines: 
DATA 248,36,246,249, 18,247,250,81,248 
DATA 291,59,249,252,87,250,253,44,251 
DATA 294,211,252,255,66,253,5, 132, 142 
DATA 22,106,223,55,82, 179,56,214, 180 
DATA 97, 164, 181,0,0,252,0,0,252 
DATA 60, 164, 184,61, 108, 185,62, 289, 186 
Modify: 
DATA &HD28E , &H4F 25, &H 1846, &HCF 76, &H47CE 


It Prog ram Listing 

REM} |{ Required marker for end of listing!!! 
.««« Type into Basic and save on same drive, 
'««« as Basic, as 'It', in Text format. 
SUB Rescue STATIC 
CLEAR :Peek10c!245000 ! 
DIM Keep$( 18) 
PRINT:PRINT "Rescue engaged!" 
.««« Find location of (MERGE "It":) in memory 
ScanMem: 

Peekloc!=Peekloc! +1 

IF PEEK(Peekloc! )<»248 GOTO ScanMem 

Flag£-0:RESTORE Peekvals 

FOR I=1 TO 7 

READ J$:IF PEEKCPeekloc!*I)€ Jg THEN Flag%=1 

NEXT I 

IF Flag=1 AND Peek10c!«127*1024 GOTO ScanMem 
Peek loc !=Peek loc! -4:Begin1!=Peekloc! :Begin2!=Peekloc! 
Peekvals: 

DATA &H9E, &H20, &H22, &H49, &H74, &H22 , &H3A 
'««« Recover decoded values and parameters 
OPEN "Garbage Bag" AS #1 LEN: 174 
FIELD #1, 128 AS N$,2 AS 1$,4 AS T$,2 AS L$,36 AS k$,2 AS Bg 
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GET #1, 1 

ID$=N$ : LengthS=CVICI$) 

Type$=T$ : Keep%(8=CVICL$) 

Kp$=k$: Pref=CVI(B$) 

CLOSE 81 

KILL “Garbage Bag" 

'««« Write beginning of file 
ID$=LEFT$CID$, Length22*" . IMOK" 
OPEN ID$ FOR OUTPUT AS #1 

PRINT 81,CHR$CPreg); 

PRINT 5*1, CHRS$CPEEKCPeek Toc! * 122; 

PRINT #1, CHR$CKeeps C02); 

PRINT #1, CHRÉCPEEKCPeek loc! +3)); 

FOR I$21 TO 18 
Keep£CIS)sVALC"&H"*MID$CKp$, 2*13- 1,22) 
PRINT 5t1,CHR$CKeepsCIS2); 

NEXT I$ 

Peekloc! =Peekloc! +22: 1%=0 

'««« Copy file until )|( marker is reached, then 
'««€ skip to rescued if Program is version 2.2 
rescue 1: 

PRINT #1, CHRÉCPEEKCPeek Toc! 2; 

Peek loc!=Peekloc!+1 

IF PEEKCPeekloc!*2)O &HAF THEN GOTO rescue! 

Fleg$-1 

IF PEEKCPeekloc!*3)O ASCC")") THEN Flag%=0 

IF PEEKCPeekloc!*4)O ASCC" |") THEN Flag£$-0 

IF PEEKCPeekloc!*5)O ASCC" (^) THEN Flagt=0 

IF Flag%=8 GOTO rescue! 

PRINT 81,CHR$COD; CHR$COD; 

IF Pre%>&HF7 GOTO rescued 

'««« Make listing an Odd length 

Begin 1!=Peekloc!-Begin 1! 
Begin1!=Begin1i!- 10900 * INT(Begin1!/1090) 

IF €1 AND INTCBegin1!))=@ THEN PRINT 31,CHR$COD; 
'««« Find end of variable names using: TenZZZ...Z 
'««« This ver MUST NOT appear anywhere else: 
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TenZ2222722222-0 
rescues: 
Peek loc!=Peekloc!+1 
IF PEEKCPeekloc! )<>»ASCC"Z") GOTO rescue3 
F lag%= 1 
FOR 1%=1 TO 9 
IF PEEK(Peekloc!+1%)<»ASCC"Z") THEN Flag%=0 
NEXT I$ 
IF Flag$-0 GOTO rescue3 
J=Peek loc! + 19 
'««« Backtrack to start of variables list. 
rescue4: 
Peekloc!-Peekloc!-1 
IF PEEKCPeekloc!-1)<>&H@ GOTO rescue4 
J=J-Peek loc! -4 
'««« If total listing is odd, skip first position. 
Begin2!=Peekloc!-Begin2! 
Begin2!-Begin2!- 1900*INTCBegin2! / 1000) 
IF C1 AND INT(Begin2!2220 THEN Peekloc!=Peekloc!+1 
'««« Print Variables table, EXCEPT: TenZ...ZZ 
WHILE J?1 
PRINT #1, CHRÉCPEEKCPeek Toc! 22; 
Peekloc!szPeekloc!*1:J2J-1 
WEND 
rescue5: 
PRINT "Voil"*CHR$C1362*"! Rescue Completed!" 
CLOSE #1 
NAME I0$ AS ID$, Type$ 
PRINT "Now loading into memory." 
PRINT "Recommend you first use" 
PRINT "'Save As' to save file..."; 
BEEP:FOR I%=1 TO 20000:NEXT IJ 
LOAD ID$ 
END SUB 
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Basic School 
Basic Wars —A First Look 


Pa 


Z DEMO 
RES 
TB DEMO [EJIIS DEMO 


SN 


Dave Kelly 
Editorial Board 


VAL R 


PCMacDEM.REL 


They've arrived! It's been a long wait but they're here. 
The Macintosh now has several new BASIC development 
tools to work with. I hope to bring you some kind of quick 
overview of the features (both good and bad) of these new 
products: 


Z Basic™ (version 3.01) Zedcor 
True BASIC™ (version 1.1) True Basic Inc. 
PCMacBASIC (version 1.60) Pterodactyl 


Ill also try to bring you a re-run in the way of 
comparison of Softworks BASIC and MS BASIC. Believe 
me, it's still not easy to pick any one version as my favorite. 
They all have their pluses and their minuses. I hope to 
present an accurate view of each. Please keep in mind that the 
vendors are working hard to correct last minute bugs or 
deficiencies and that a follow-up article will report on how 
successful these efforts have been. 

Before we get into any of the features, here is the first 
benchmark that we use for our comparison. This is the same 
benchmark that was presented in the May 1986 MacTutor. 

Accuracy Benchmark 
(See Table 1) 


40 time 1=TIMER ‘REM Use TIME for Softworks Basic 
58 s=0 

100 x=9 

200 FOR n=1 TO 1000 

308 s-s*x*x 

400 x-x*.00 123 

500 NEXT n 

600 PRINT s,x 

108 time2- TIMER 

800 Totaltimestime2-t ine] 

900 PRINT “Elapsed Time =", Totaltime, "Seconds." 


This same benchmark has been run on various desk top 
computers to compare their speed and accuracy in engineering 
or scientific applications. Most desk top computers convert 
real numbers to their binary equivalent before performing 
Software math operations. This introduces an error depending 
on the precision of the math routines that can propagate 
through many math operations, producing a considerable error 
in the final result. This benchmark program, developed by R. 
Broucke at the University of Texas, Austin, tests for this error 
propagation. See Table 1 for the results on different 
computers. 

Accuracy in these computers is a function of the number 
of bytes used to represent the mantissa. A three byte mantissa 
is used in most versions of Microsoft BASIC (single 
precision). This is illustrated by the systems that give 
503.545 for an answer. The TRS-80, Altair 8800, Osborne 
MBASIC and IBM personal computer are typical of this 
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version of Microsoft BASIC. Those versions of Microsoft 
BASIC implemented on a 6502 microprocessor typically use a 
four-byte mantissa, giving 503.543832 or something similar 
as the answer. Note that only those computers NOT using a 
Microsoft version of BASIC come up with the right answer 
(with the exception of the decimal version of Macintosh MS 
BASIC). The HP 9836 uses 6.5 bytes or 52 bits to represent 
the mantissa, and 11 bits to represent a 3 digit exponent! This 
is why the HP 9836 has such a high precision compared to the 
other desk top computers. 

The speed of each computer is related to the efficiency of 
its BASIC interpreter and the clock speed of the computer. 
Most of the 6502 based systems run at 1 mHz, while the Z-80 
systems typically run between 2 and 4 mHz. The reason there 
is not more of a difference between the running speeds of the 
6502 and the Z-80 is because the 6502 is very efficient in 
addressing memory, and hence the BASIC interpreters on the 
6502 machines are much more efficient than the Z-80 based 
interpreters. This difference is particularly true for the APPLE 
II versus the TRS-80 model II, which runs at more than twice 
the clock speed of the APPLE, yet is nearly identical in the 
accuracy bench mark speed. The Macintosh runs at 7.8336 
mHz, one of the fastest on the list. The difference between an 
interpreter and a compiler is shown by the fact that the HP 
9836 PASCAL runs twice as fast as the HP 9836 BASIC for 
this bench mark. This is also evident from the comparison of 
compiled Basics and interpreted Basics on the Macintosh. 

Remember that any benchmark test only checks specific 
attributes of the language. Other areas may have strengths or 
weaknesses which the benchmark cannot address. Of the 
Macintosh Basics available, it appears that True BASIC is 
fastest of those languages giving the correct answer, with Z 
Basic, PCMacBASIC and MS Basic (d) being the only other 
Basics to give a correct answer. True Basic's math routines are 
impressive in accuracy, speed, and breadth. 

The Sieve of Erastothenes benchmark results shown in 
TABLE 2 indicate that Z Basic overall is the fastest BASIC 
available. That is reasonable since Z Basic is compiled. True 
Basic has very good results for being an interpreted language. 
One glaring result is the PCMacBASIC time on the Sieve is 
66 seconds, significantly slower than Z Basic. The reason for 
the apparent slow time is that PCMacBASIC uses dynamic 
arrays, which can be re-dimensioned and even spooled to disk 
as virtual arrays. The extra overhead of keeping track of the 
dynamic array size when addressing elements in the array is 
magnified by this benchmark and accounts for the time 
difference between it and Z Basic, which uses standard fixed 
arrays. This is a powerful feature, but one that has a trade-off 
in execution time when a lot of array addressing is involved as 
in the Seive. 
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DEFINT a-s 


19 DIM FLAGS(8 19 1) 
20 PRINT "19 iterations" 


22 T-TIMER 

30 FOR M = 1 TO 10 
48 COUNT = 

50 FOR i = 1 TO 8191 
68 FLAGSCi) = 1 

70 NEXT i 


80 FOR i = 1 TO 8191 

99 IF FLAGSCi) = Ø GOTO 170 

100 PRIME = i+ i+3 

PRINT PRIME 


105 REM 


110 K = i + PRIME 
120 IF K <= 8190 THEN 

FLAGSCK) = Ø:K = K + PRIME:GOTO 120 
168 COUNT = COUNT + 1 


170 NEXT i 
188 NEXT M 
181 T2: TIMER 


Sieve Benchmark 
(See Table 2) 


Computers giving the RIGHT answer: 


Computer 
HP 9836 
MACINTOSH 
HP 9836 
MACINTOSH 
MACINTOSH 
MACINTOSH 
MACINTOSH 
MACINTOSH 
CROMENCO Z-2 
OSBORNE 1 
ALTAIR 8800 


Software 
PASCAL 


True Basic (with formatting) 


BASIC 


MS BASIC (d) ( single precision ) 
MS BASIC (d) (double precision) 
MS BASIC (b) (double precision) 
PCMacBasic (double precision) 
ZBasic (13 digit accuracy ) 


BASIC 
CBASIC 
EXT. BASIC 


Computers giving the WRONG answer: 


Computer 
MACINTOSH 
MACINTOSH 
MACINTOSH 
MACINTOSH 
MACINTOSH 
HP-150 
MACINTOSH 
VECTOR GRAPHICS 
IBM PC 
OSBORNE 1 
NEC PC8001A 
HP-85 
SINCLAIR ZX81 
ATARI 800 

T.I. 99/4A 
APPLE IIl 
TRS-80, II 
APPLE Il 
VIC-20 

PET 

ALTAIR 8800 
TRS-80 COLOR 
TRS-80, III 
TRS-80, | 
SINCLAIR 2X81 
TRS-POCKET 
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Software 


True Basic (no formatting) 


Softworks BASIC 


r Benchmar 


Pterodactyl PCMacBASIC (single precision) 


MS BASIC(b) (single precision) 


ZBasic (12 digit accuracy, double precision) 


GWBASIC 


Softworks BASIC (formatted) 


BASIC 
MBASIC 
MBASIC 
BASIC 
BASIC 
FAST 
BASIC 
BASIC 


BUSINESS BASIC 


BASIC 
APPLESOFT 
BASIC 
BASIC 

3.1 BASIC 
BASIC 
BASIC 
BASIC 
SLOW 
BASIC 


190 PRINT COUNT; "primes"; T2-T; "Sec." 
200 FOR i=1 TO 10:BEEP:NEXT i:END 


The Basics Compared 
The decision of which version of BASIC is the best is a 
tough one. I've tried to determine which attributes I would 
like to see most. For the Macintosh there are also some 
considerations that don't apply to the average computer. (After 
all thats why the Mac isn't your average computer!) A few of 
the attributes that I feel are important are (not necessarily in 
this order): 
1. Support of the Macintosh Standard User Interface including 
proper implementation of Menus, Windows, Controls, etc. 
2. Compatibility with HFS. 
3. Access to the Macintosh Toolbox routines. 
4. Ease of use. (Editing, documentation, etc.) 


5. Speed 
6. Reliability (How much does it BOMB?) 
7. Price 
- TA 
Micro $ X Time (s) 
68000 503.543802149991 1.23 0.52 
68000 503.543802150 1.23 0.93 
68000 503.54380215 1.23 1.12 
503.54380215 1.23 4.00 
503.54380215 1.23 4.00 
503.5438021499906 1.229999999999996 4.00 
503.543802149991 1.23 4.00 
503.54380215 1.23 4.00 
Z80 503.54380215 1.23 10.50 
Z80 503.54380215 1.23 14.00 
8080 503.543802149999 1 1.23 237.00 
Micro S X Time (s) 
68000 503.544 1.23 0.87 
68000 503.544 1.23 3.0 
503.545 1.230001 3.0 
503.545 1.230001 3.0 
503.543802129 1.23 4.0 
8088 503.545 1.230001 5.27 
68000 503.54380196 1.22999999 6.0 
280 503.545 1.23 7.0 
8088 503.545 1.230001 7.5 
Z80 503.545 1.23 8.0 
280 503.545 1.23 11.0 
- 503.543802171 1.23 11.0 
280 503.54383 1.23 13.5 
6502 503.543594 1.23 15.5 
9900 503.5438022 1.23 18.50 
6502 503.545 1.23 20.00 
280 503.545 1.23 23.00 
6502 503.543832 1.23000004 26.00 
6502 503.543832 1.23000004 27.00 
6502 503.543832 1.23000004 30.00 
8080 503.545 1.23 36.00 
6809 503.543832 1.23000004 37.00 
Z80 503.545 1.23 43.00 
280 503.545 1.23 48.00 
280 503.54383 1.23 81.00 
- 503.5438022 1.23 600.00 
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hen 
(1900 Primes - 10 iterations) 


leve of Era 


Com puter 
MACINTOSH 
MACINTOSH 
MACINTOSH 
HP 9836 
MACINTOSH 
MACINTOSH 
MACINTOSH 
HP-150 


Software 
Z Basic 
Pterodactyl PCMacBASIC 


True Basic 
BASIC 4.0 
Softworks Basic 
MS Basic(b) 
MS Basic(d) 
GWBASIC 


Of a lesser importance is: Compatibility with versions 
of Basic on other computers. In most cases the major impact 
of this is to help sales of BASIC. Most Macintosh 
programmers (99% of them) want to write toolbox programs, 
which by their very nature, will not be compatible with other 
computers anyway. The only place where compatibility 
counts is when it helps make programming easier because the 
BASIC commands are similar, such as compatibility with MS 
Basic on the Mac. 

Both Z Basic and True Basic have taken great pains to 
present a family of compatible Basics for different machines. Z 
Basic is available on several other computers including Apple 
//, MS-DOS based systems, and Z-80 based systems. True 
BASIC on the Mac is compatible with True BASIC on the 
IBM and the Amiga. Z Basic appears to have done the best job 
of not crippling the Mac version for the sake of this 
compatibility. Toolbox support is available both by direct 
calls to the toolbox and by Basic statements similar to MS 
Basic which greatly simplify the coding of the Mac interface. 
True Basic, on the other hand, requires a greater separation 
between it's normal environment, which it tries to keep 
compatible to versions on other machines, and the Mac 
interface. This separation means more work on the 
programmer's part to implement a true Mac like program, 
since everything must be done at the toolbox level of detail. 
Of the two, Z Basic is the most compatible with MS Basic on 
the Mac and in fact, is the closest to being an MS Basic 
compiler. But True Basic is very compatible in syntax with 
HP 9836 Basic and includes a very fine set of matrix 
commands no other Basic outside of HP has. 

PCMacBASIC, as the name implies is compatible with 
IBM PC BasicA and programs written for the IBM can be 
easily ported over to PCMacBASIC and run on the Mac. 
Again, the Mac interface access is not crippled by this 
compatibility, as complete toolbox access is provided for, 
both as Basic commands and direct toolbox calls. This feature 
might be important if there are IBM PC programs you wish to 
port over to the Mac, that were done in BasicA. 

Compatibility is really a secondary issue. Most of us 
only have one kind of computer anyway. Even if a ported 
program did run, it wouldn't follow any Macintosh standards 
which means they would have to be modified, and toolbox 
calls added to make them "Mac-like". Why bother? It would 
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Benchmark Results TABLE 2 


be much better to design the program 
from the ground up for the Mac in the 
first place, in which case, you wouldn't 
care that your code was compatible with 


Time XYZ's computer. 
i HFS Issues 


66.0 
121.033 
248.7 
525.0 
670.0 
690.0 
1478.36 


The use of the Macintosh standard 
interface is an attribute that is a must for 
any language. Show me a program that 
supports the Standard User Interface and 
I'll show you one that is easy to learn to 
use. Its the Macintosh way! 
UNFORTUNATELY, there are some 


programmers out there that don't follow it very well. We've 
all seen the results of this when HFS was released. Those 
programs that don't conform to the standard have had to be 
modified to work with HFS (i.e. software updates). Some of 
the programs still exist without modifications, indicating to 
me that the programmers just don't care if it follows the 
standard or not. Well, I care! In fact, one of my first 
questions that I ask before buying any new software is "Is it 
HFS compatible?", and "Does it follow the Mac Standard User 
Interface?". That's dangerous though, because some of the 
incompatibility is subjective. For example, MS Basic is 
useable with HFS, but depending on the program, you may 
have to have things located on the root directory. (Take heed 
Microsoft, MS BASIC is NOT 100% HFS compatible.) 
Some software packages claim to be compatible with HFS 
when in fact this only means that it can be made to work 
around HFS. As it turns out, some files (usually support files, 
help files or similar type files) must be on the root volume or 
in the same folder as the application. I'm not so sure if this 
can really be called HFS compatibility or not. 

HFS compatibility should mean a program can find it's 
own working files no matter where the user chooses to put 
them! We have already published an HFS Lost File Finder 
DA. A similar tree search subroutine can be added to any 
application to search the directories for it's working files. 
Developers simply have been too lazy to implement this 
properly. At the very least, a simple standard file dialog box 
can be called up to ask the user where he put the needed 
intermediate file. Recently some programs have been taking 
this approach (Spellswell for its dictionary file) and we think 
this is much better than artificially confining the needed file to 
a certain folder or disk. 

All the versions of BASIC claim to work with HFS. 
PCMacBASIC needs certain .REL files (included in a runtime 
folder) to be on the same disk as the object being compiled, 
and in the same folder as the user's compiled object file, which 
is not what you would expect. A dialog box is presented which 
allows the user to select through the standard file dialog, where 
his source, resource, listing and object files are located. This 
works nicely, but having to place the system's ".REL" files in 
the folder with the user's object file is unwieldy. The reason it 
was done this way was to get around HFS incompatibilities 
with the MDS and McAssembly assemblers and linkers. The 
McAssembly assembler and linker are built into 
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PCMacBASIC, which assembles and links the Basic source 
into a stand alone application. So HFS problems strike home 
in round about ways. This Basic also provides HFS 
commands for your programs so they can create and access 
folders correctly. None of the other Basics yet consider the 
HFS compatibility requirements of the user's programs. 

The Basics that require the use of the MDS editor already 
have some problems because the MDS editor itself is not yet 
HFS compatible. There are other commercial editors available 
which will work just fine, such as QUED. These HFS 
incompatibilities are not fatal to the use of the products 
involved. We can suffer with it till updates are provided. Z 
Basic has some problems with HFS in the command mode 
which Zedcor tells me they are working on fixing for the next 
release. Otherwise, during program execution there doesn't 
seem to be a problem. We have already reported on how MS 
Basic must be in the same folder as it's library files and source 
program. 

Mac User Interface 

When the implementation of menus, windows and 
controls etc. in each of the BASIC versions are compared, 
differences become apparent. All of the versions reviewed 
seem to make use of menus. Menus should give access to 
desk accessories and at least have the File and Edit menus as 
standard. Controls that are in windows should work. That is, 
if there is a go-away box, size box, buttons, and/or scroll 
bars, they should work. Although you can define your own 
windows with Z Basic, the default window (appears when no 
window has been opened) has a go-away and size box that 
won't work unless your program is checking for it. Because Z 
Basic is compiled, there is some responsibility for the 
programmer to see that the functions all work. Most of the 
time the default window is used for quick programs that you 
don't want to spent a lot of time developing the output. I 
suggested to Zedcor that they use a default window with no go- 
away or size box so that they would not be present unless the 
user wanted to program them. (To do otherwise, violates the 
standard interface guidelines by having controls present which 
are not implemented.) They indicated they would check into 
that possibility. Windows and controls in Z Basic are accessed 
with commands almost the same as MS BASIC (some MS 
Basic programs may run with no modification in Z Basic). 
However, there are some differences. First of all, even 
though event trapping is done similarly to MS BASIC, they 
won't function correctly unless you flush out the queue 
occasionally. Events are stored on the queue as they occur 
(each mouse click and menu selection for example). This will 
be discussed in a future column involving Z Basic. One item 
that seems to show a problem involves the use of windows. 
In Z Basic when multiple document type windows are used, 
selecting the title bar of the document window should make 
the window active. Well, it doesn't. You have to select inside 
the window content region (everywhere except the title bar) to 
make the window active, another violation of the interface 
guidelines. These little bugs are being chased out of all the 
Basics reviewed here, and is one reason why there is no clear 
cut winner yet. 
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Z Basic Tops But Still a Few Bugs 

Z Basic is my favorite for speed of execution. It is nice 
in that it supports the same MENU, Window, and control 
functions as MS BASIC. If you know MS BASIC, you 
already know many of Z Basic's commands. The manual is my 
favorite too. It is well written, in a reference style that makes 
finding things very easy. The breadth of instructions in this 
Basic is amazing. Even Appletalk access is provided for. 
Everyone wants double-clickable applications. Z Basic is an 
easy way to get fast compiled programs which are double- 
clickable, with very good MS Basic compatibility. But beware 
that there may be some strange bugs, like the one mentioned 
above with windows, that we don't know about. There were at 
least a couple of routines that didn't work properly (Eject and 
DIR). I was told these would be fixed in a future version. 
Another problem occurred when I tried to transfer to MDS Edit 
from the Edit menu. The System crashed with an error 26. 
Also, smooth scrolling is not implemented in the Z Basic Edit 
window. The screen "jumps" up and re-paints itself instead. 

Line Numbers 

One annoying thing is that in all of the other "modern" 
versions of BASIC line numbers are optional. In Z Basic they 
are required by the compiler. Zedcor told me that this was so 
that the compiler could keep track of which line was being 
compiled and that when errors occurred you could get feedback 
as to which line has the error. This doesn't have to be a big 
problem because you can use the MDS (or equivalent) editor 
without line numbers to write your program, then load it into 
Z Basic and compile it. The Z Basic editor automatically adds 
the line numbers. Also, you may save the program with or 
without line numbers so that it could be re-edited if desired. 
So, if you are using MDS Edit, you can act as if there were no 
line numbers, since they are only inserted when you load and 
compile the program. 

PCMacBASIC also requires line numbers for GOTO's 
and GOSUB's. This is the only Basic in which line labels are 
not allowed. Boo! 

toolbox Support Important 

It is a "must" to have access to the toolbox. I've talked 
about this in the past when reviewing Softworks BASIC. I 
like the ease of use of MS BASIC to set up menus and 
windows quickly. All of the new Basics reviewed here support 
the toolbox. The implementation and documentation available 
becomes the issue here. MS BASIC, as you know, can only 
call the toolbox through library routines. Very few routines 
are included in the language. Independent vendors (like CLR) 
have provided for this omission by providing a more complete 
set of library routines to access the Mac ROMS. 

Toolbox access has been provided for in True BASIC 
through subroutines that can be called from your program 
(This support appears to be very complete). However, True 
Basic forces a complete separation of the toolbox and True 
Basic environments. If you use the toolbox for windows, as 
we did in our example, you have to pass control of the Mac to 
your program and do everything in toolbox syntax. This 
means you are really writing a Pascal or Assembly program 
using Basic syntax, because of the amount of detail you must 
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deal with at the toolbox level. Look at the True Basic example 
and you'll see how much more detailed (even to the point of 
calling System Click) the program is, and how much longer 
as well. Yet, for all your flexibility in writing real toolbox 
programs, your still programming in an_ interpretive 
environment so no double-clickable application despite the 
Mac like code. A runtime package is available but we think 
that should be a part of the standard language so full 
compilation can be obtained any time you want it. 

You may use direct toolbox calls using Z BASIC (a 
complete list of calls is found in the manual, but no 
examples), Softworks BASIC (see May 1986 MacTutor) and 
PCMacBASIC. The method of implementation is important 
because if new toolbox routines are added, will the Basic be 
able to call them or will the user need a new interface file from 
the vendor? In this regard, PCMacBASIC probably has the 
most powerful toolbox interface of all. It allows the user to 
call virtually every toolbox trap in existence, and even those 
not in existence, since the user defines the interface himself by 
using the MDS trap equates file and the USER function. This 
approach will also appeal to old Apple II users who liked to 
extend Basic by calling custom assembly routines. You have 
complete freedom to reach any toolbox routine in the Mac. 

Documentation support for the toolbox is lacking in all 
the versions reviewed except True Basic. Z BASIC and 
Softworks Basic provides a list of Toolbox calls in an 
appendix of the manual. Zedcor has told me they plan to 
release a manual on programming with the toolbox, but I 
don't know when or how much that will be. The manual for 
Z Basic is the nicest of the bunch so I expect the Toolbox 
manual to be very well done. They devote a 115 page section 
on Z Basic on the Mac (the next largest section is 56 pages for 
MS-DOS). True Basic provides very complete documentation 
on a "Toolbox" disk. PCMacBASIC's manual has a very very 
limited section on how to call some of the quickdraw routines 
(same routines as MS BASIC), but documentation is so 
incomplete or hard to understand that I couldn't fully 
implement the toolbox routines. A revised manual is currently 
being prepared that will correct this. 

Why Standardize? 

You may be interested to know what the American 
National Standards Institute (ANSI) committee X3J2 has been 
doing lately. Thomas E. Kurtz, one of the authors of True 
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Fig. 1 Our sample window and menu in Z Basic 
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Basic is chairman of that committee. He is also co-author of 
the original, "Dartmouth" BASIC. The ANSI committee has 
proposed a standard for the advanced features of BASIC. This 
Standard was the result of many years of deliberations, and it 
sets the stage for implementing the same version of BASIC 
on all the leading personal computers. The committee 
believed that the original basic concepts of Basic had been 
corrupted and it was their duty to mankind to give Basic an 
overhaul. True BASIC is the only version that Closely 
conforms to the ANSI Standard. If anything should be a 
standard, I think it ought to be the ANSI Standard. In addition 
to the older GOTO and GOSUB statements, True BASIC 
provides control structures like IF-THEN-ELSE, SELECT- 
CASE (not found on any other Macintosh BASIC), DO- 
WHILE (also not on any other version), DO-UNTIL (also not 
on any other version). The instruction set in general is very 
close to HP 9836 Basic and is the nicest implementation of all 
the Basics, considering just the traditional Basic commands. 
True BASIC provides window and graphics commands, 
however some of the Macintosh input and output features (for 
example, windows and menus) are incompatible with True 
BASIC input and output (for example, INPUT and PRINT). 
The graphics routines are mostly compatible, that is, your 
program can use the ROM routines for special graphics and 
True BASIC for everything else. This means that to make 
your programs "Mac-like" you may have to do more through 
the Toolbox subroutines than you would in Z Basic or MS 
BASIC. It should also be noted that in order to really use 
the Toolbox well in any of the languages, you have to 
abandon many of the quickie implementations of the Toolbox 
(like MENU, WINDOW, DIALOG etc.). You can't mix 
windows created by Z Basic or True Basic with the windows 
created by the Toolbox! The solution is to use the Toolbox 
for as much as you can. The same work (using "Inside 
Macintosh") would have to go into a program in 
PCMacBASIC or Softworks BASIC also. True Basic comes 
with two disks. One is the program disk with programs and 
examples. The other is the Toolbox disk which contains 13 
libraries of subroutines and functions that let you access the 
Macintosh ROM routines (except on 128k Mac due to space 
limitations). There is a little bit of documentation on the 
Toolbox disk, but most of what you will need to know is in 
"Inside Macintosh". 

This still doesn't explain why all these different versions 
of Basic need to "standardize". Most statements implemented 
in MS BASIC are somewhat standard in other versions of MS 
BASIC making it easy to convert programs from one 
computer to another. In fact, most Z Basic commands match 
MS BASIC commands in form, fit, and function (with some 
exceptions). I'm still not sure that any one standard will ever 
be accepted either. It may take awhile for ANSI to invade the 
MS BASIC "standard" especially if there is no way to create 
stand alone applications without investing a fortune. It appears 
that when writing a program you have to decide right from the 
Start if you want to use menus, windows, dialogs etc. If you 
do, don't bother with the "standard" implementation, but just 
use the Toolbox for the entire program, but then you give up 
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the ease of use of a Basic language in the first place. This is 
particularly frustrating with True Basic. It's a nice thought to 
think that all Basics in the world could be compatible with 
each other, but if you really want to make a good professional 
looking program you'll want to follow the Macintosh Standard 
User Interface by writing your program with the Toolbox. 

I'd like to mention that since True Basic is interpreted, 
you have to load the interpreter to run your program. Double 
clicking on a True Basic document from the Finder loads True 
Basic and then the document, but doesn't run the document. 
What we really want is True Basic compiled double-clickable 
applications! True Basic has a compiled mode for the 
programs which makes them non-listable, but still interpreted 
although it may run slightly faster than non-compiled and you 
don't have to worry about linking library subroutines to the 
"compiled" versions. True Basic only compiles to an 
intermediate code. Note that the two main complaints with 
True Basic of not being a compiler and the extreme separation 
of toolbox mode from True Basic mode, act to reinforce each 
other, making the problem even more exasperating. 

PCMacBASIC is ".REL" File Compatible! 

The PCMacBASIC compiler compiles your program into 
double-clickable applications, linkable object (.REL file), 
McAssembly source, or MDS source. Now that's what 
programmers want! The ".REL" file icon for PCMacBASIC 
programs is identical to the icon produced by the 
McAssembler (which is convertible to MDS ".REL" file 
format). The latest version also supports MDS ".REL" file 
formats directly, in addition to the McAssembly format and 
conversion utility. If only the execution speed were faster. The 
use of both dynamically dimensioned arrays and Apple's 80-bit 
SANE routines combine to make floating point operations 
significantly slower than Z Basic by our tests. SANE is very 
accurate, but very slow. This could be an important minus if 
your application requires heavy floating point processing. Z 
Basic is just as accurate as PCMacBASIC, but considerably 
faster in executing double precision arithmetic. 

PCMacBASIC programs are written on an editor such as 
the MDS editor. A resource file is also necessary to give 
information about the resources used in the program. Menus, 
windows, controls, alerts, and dialogs are all done as resources. 
This may be somewhat intimidating to a new Basic 
programmer, but probably more familiar for an experienced 
programmer since if follows the "traditional" Mac 
development cycle. In fact, this Basic is more like Pascal or 
assembly development on the Mac than any of the others, a 
distinct plus if you are familiar with Mac programming. 

Toolbox routines and assembly language may be 
programmed within PCMacBASIC through use of the USER 
function (Example: USER ".word $A888" or USER 
_TextFace(FONT%) will call the Textface ROM routine). 
Note that the MDS toolbox equates file may be included in 
your source to provide a symbolic trap interface, and that this 
can be extended by the user to new traps or custom routines. 
In other words, this Basic allows 100% toolbox compatibility 
now and in future machines, since you are not dependent on a 
vendor supplied glue file. You can also mix Basic and 
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assembly by placing each line of assembly code in quotes and 
using the USER function. This allows you to call register 
based traps from Basic by coding in line a simple assembly 
routine to pull the Basic variables off the stack, set the register 
values, call the trap, and restore the stack upon returning to 
Basic. You can also use the CALL statement and link 
assembly routines to your Basic program in the traditional 
compiler/linker approach. Assembly language programming 
from within Basic is not provided by any other version of 
Basic. This is a definite plus for PCMacBASIC and one that 
makes it a strong contender, if the documentation is 
improved. 

The McAssembly resource compiler is built into the 
PCMacBASIC compiler to compile the resource file. 
PCMacBASIC also provides a way to convert function keys 
from the IBM PC (if used in the program you port from the 
IBM) to menu items. This feature may please those hard core 
IBM groupies, but probably is of little interest to most Mac 
people. Like True Basic, toolbox access is an all or nothing 
affair. All menus, windows, dialogs, and controls have to be 
implemented in resources. There are no MENU or WINDOW 
commands like MS BASIC to define your own windows etc. 
The MENU and WINDOW commands included in 
PCMacBASIC are for calling the resources created at compile 
time. This can be interpreted as a plus or a minus depending 
on your orientation. 

Presently, the manual is inadequate to figure out how to 
implement much of the toolbox. An improved manual is 
being written which may show their implementation to be 
highly desirable so keep your eye on this one. The method 
they chose to implement toolbox calls with the USER 
function, may be good or bad depending on what you are used 
to. It requires that you have an understanding of Assembly 
language in order to define your own USER functions for the 
Toolbox. We think this is an asset, but the next version will 
provide a complete file of toolbox USER interfaces and 
example programs for beginners unfamiliar with trap calls 
from assembly. Of all the products, this one is most dependent 
on which way the documentation goes. A good set of 
predefined Toolbox calls provided on disk along with 
examples and docs could make this a top notch product 
because of it's close association with assembly development 
on the Mac. 

A few little funnies were found in version 1.6 and 1.65: 
it seems when you exit a program, somebody paints an 
annoying small black rectangle in your window before exiting 
to the desktop. I'm told this box is the cursor in reverse field, 
indicating that an invisible cursor is being carried about as an 
IBM PC compatibility holdover. We'd like to see the cursor 
go away. Another little bug is a dialog box that comes up 
when you identify your source and resource files. The dialog 
box nicely warns you of the HFS restrictions that your files 
have to be in a certain place, but the bug is the dialog box 
shows up twice in succession when you click OK before 
going away for good. This is being fixed. 

If you want to try to compile your MS Basic programs, 
then Softworks, PCMacBASIC or Z Basic is your only choice 
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at the present time. Z Basic offers the most syntax 
compatibility. PCMacBASIC is slower, but may give you 
some flexibility if you want to link to other languages 
because of its compatibility with the REL format. MacTutor 
is a #1 supporter of the .REL format, and is encouraging 
Apple to provide conversion routines from the .REL format to 
MPW so that object code can be linked with the new Apple 
development system without re-compilation. (This addition to 
MPW is being debated at Apple. Contact Paul Zemlin at 408- 
9773-3711 and voice your opinion on this issue.) 

The True Basic manual is printed nicely and spiral bound 
by Addison-Wesley, but both PCMacBASIC and True Basic 
manuals are not easy to use as reference manuals. True Basic 
is the only one with a User Manual (tutorial with Mac specific 
information) and a Reference manual (common to all versions 
of True Basic), but the reference manual is not what you 
would expect. The Z Basic manual is a true reference manual 
in the spirit of HP manuals. The True Basic reference is again 
written like an instruction manual similar to the User manual 
and it is not clear what rightly belongs in each manual. It 
would have been nice to have another manual for Toolbox 
calls too. True Basic has done a nice job of writing 
subroutines for all the libraries. The problem is that you have 
to print off another whole book worth of documentation from 
the disk in order to have a reference for the Toolbox. Overall, 
the True Basic documentation on disk (for the toolbox) is still 
the best of all the versions reviewed here, which is another 
way of saying how far we have to go to figure out how to deal 
with the incredible amount of information required by the 
"toolbox language”. 

Now for the my biggest complaint about True Basic: 
The language is interpreted and not suited for creating 
applications without the run time package. They want $500 
for the run time package to compile to stand alone 
applications. We at MacTutor feel that the run time capability 
should be included in the price of the interpreted True Basic. It 
is Clear to us that our readers want to be able to create stand 
alone applications. All of the competition (Z Basic, 
Softworks, PCMacBASIC) have provided stand alone (double- 
clickable) capability with their basic price. Maybe with a few 
of your comments (cards/letters not phone calls) they might 
realize just how important it is to be able to create independent 
applications (hint, hint!!) 

The Z Basic manual is Laser printed, soft cover bound 
(same manual for all versions of Z Basic) with an excellent 
format (very easy to find information in this one). The manual 
is the main reason why Z Basic has to rate a slight edge at the 
present time, despite the bug chasing. It is simply a very well 
done manual. 

The PCMacBASIC manual is the only one that had 
information about using HFS directories in your programs. 
Commands are provided for your Basic program to make or 
change an HFS directory (folder), an indication of HFS 
compatibility (even supports Zoom Window!). This is an 
important point that all the other Basics should take note of. 
Not only does the compiler need to be HFS friendly, but the 
user's programs also have to be HFS friendly. Interestingly 
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enough, PCMacBASIC itself needs a better HFS design. 
Vendors: try your product on a Mac Plus. Just how 
compatible is it? Does it still work if you move things around 
or add folders or change file names? If you can't make it fully 
HFS compatible, then do the next best thing and fully explain 
to the user what the HFS restrictions are. Not enough 
attention has been given to the HFS issue in any of these 
Basic products. 
BOTTOM LINE: What's the best? 

What's the best BASIC? That has a very subjective 
answer. At the present time, I'm not going to endorse any one 
version of BASIC over another, although Z Basic seems to 
have a very slight lead. You might say the votes are not all 
counted. Z Basic seems to be the fastest and a very interesting 
language, but still has a few bugs. PCMacBASIC has the 
ability to create .REL files, but needs a new manual, with 
better toolbox coverage and is slow. True Basic supports the 
ANSI standard and seems to be a solid program, but 
completely separates toolbox mode from True Basic mode and 
is not compiled. MS Basic has the best implementation of the 
Macintosh user interface, but has limited toolbox access and is 
very slow. Softworks Basic has structured declared variables 
making it somewhat easier to use Inside Mac when designing 
your program, but the declared variables are not part of any 
"standard" implementation of Basic, making programs look 
much different from anything else. In conclusion, each product 
has a plus and a minus, so that they all equal out. The next 
level of revisions and updates should be very interesting as we 
see who gets the most minuses out while retaining the most 
pluses. 

It has been the intent of this column to give you a 
general overview of each of these new products so as to wet 
your appetite for the future, and to encourage the vendors to 
move their products in certain directions. It is too early to tell 
for sure which one will meet your particular needs until the 
next level of revisions come out. I feel what we've really done 
is pointed out how each product has disappointing 
shortcomings at this time. I'd be very interested to know what 
your Own opinions are concerning the Basics we've discussed. 
In the months to come, we will find out more about these new 
versions of Basic as we study how they work and how to 
program with them. Send in your votes as to which 
one you would like to see more MacTutor 
coverage of. In the meantime, you can expect somewhat 
equal time for each of them. I have flipped my opinion of 
each of the Basics back and forth several times while doing 
this review. I have compiled a comparison chart showing 
some of the major items that are important for each version. 

Code Examples of Each Basic 

For comparison I have written a Menu/Window demo in 
each of the Basics reviewed here. The Softworks example 
appears in the May 1986 MacTutor. A few changes had to be 
made to some versions to even come close to the MS BASIC 
(original version). 

To implement the demo in Z Basic required placing 
quotes around labels, add the WINDOW COORDINATE 
statement (for Macintosh screen coordinates) and replace the 
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Textface,Textfont, Textmode calls with the TEXT statement 
(for use with Z Basic defined windows and graphics). The 
system configuration must be set for Locate y,x (ON). It is 
not necessary to remove old menus as we did in MS BASIC 
so a few lines may be deleted for that. Be sure that the New 
York font is on your disk. I tried to implement the demo in Z 
Basic with all Toolbox calls, but I ran into problems with 
incompatibilities between the Z Basic commands (for 
windows, menus) and the Toolbox calls. It is difficult (or 
impossible) to mix Toolbox and Z Basic windows and menus. 

Before I could implement the True Basic version, I had to 
print out all the Toolbox documentation (about a one inch 
thick stack of computer paper). During the printing process 
(using Imagewriter 2.3, System 3.2) I had several system 
bombs (the only ones I ever had with True Basic). Using the 
example programs provided, it was very easy to create the 
demo program with mostly all toolbox commands. Notice 
that True Basic even has a command to give control of the 
Mac to your program (TAKEMAC) or return it back to True 
Basic (GIVEMAC). This is to separate the True Basic 
implementation with the Toolbox commands. The program 
worked great with no real pain. By the way, Toolbox 
commands don't work on a 128k Mac, not enough memory. 
Too bad it doesn't compile to a stand alone application. All 
comments in True Basic must use the exclamation point 
instead of the single quote used in Z Basic and MS BASIC 
(also supported by PCMacBASIC). 

The PCMacBASIC implementation was a custom 
implementation to match the PC  BasicA translation. 
Documentation wasn't clear about how to set up menus or 
how to call the toolbox. This was the hardest version to 
implement. A lot of work needs to be put into the 
documentation. 

If you recall, the Softworks Basic demo in May also 
showed how to load the fonts and sizes into menus. This was 
not implemented on this demo, however it should be noted 
that implementation of the font menu would be most difficult 
in PCMacBASIC, without the new manual. It would be 
somewhat awkward to implement in Z Basic, unless you are 
using Toolbox calls for everything. In True Basic, you have 
to be committed to using Toolbox commands in order to 
implement any menus at all. 

In conclusion, I hope that my review here will help to 
bring about improvements in all of the versions of BASIC 
presented here. As I said before, I can't say any one is better 
than another one yet. With the right kinds of changes it is 
possible that any one of them could jump way ahead of the 
the others in usefulness. More to come next month. 

MS Basic Demo 

Here is our sample toolbox program to display a window 
and menu selection. We use this program to see how well each 
Basic can implement the basic Mac event loop, display a 
window and allow the user to make choices in a menu. Look 
over this familar MS Basic version, then compare this with 
the equivalent code of the other three Basics to see how they 
differ. 


* Menu/Window Demo 
* MS BASIC(b) or MS BASIC Cd) version 
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' by Deve Kelly 

' 61986 MacTutor 

' No control of Desk accessory menu 
' Clear old menus & set up new menus 
MENU 1,2, 1, "File" 


b 
[d 

~ 
2 
c 
ando. 
e 


, Item 1" 


,0,9, LLLI 
ON DIALOG GOSUB HandleAct:DIALOG ON 
start: 
' open sample window 
WINDOW 1,"",C100, 1002- (400, 225)5,2 


HandleAct:MENU STOP:MOUSE STOP 
ACT-DIALOGC? ) 
IF ACT=5 THEN GOSUB Setupwindow 
MENU ON: MOUSE ON 


Benuevent: 
menunumber-MENUC?) 
menuitem-MENUC 1) : MENU 


ON menunumber GOSUB menu1,menu2,menu3 
RETURN 


menui: 
IF menuitem=1 THEN Quit 
RETURN 


men2: 
‘This is the Edit menu 
‘use it for DA's only 
RETURN 


menus: 
LOCATE 3, 1 


PRINT"You have selected menu item” ;menui tem 
RETURN 


Setupwindow: 
as 


CALL TEXTFONT(2):CALL TEXTSIZEC 12) 
CALL TEXTFACEC 1) 


PRINT "MacTutor shows you how it works!" 


CALL TEXTFACECO) 


LOCATE 5, 1:PRINT"MS BASIC Version 2.1 demo" 


Activityst 


Z Basic Demo 
Note that this version is very similar in syntax to the 
MS Basic program. In fact, Z Basic comes the closest to being 
a full MS Basic compiler, with the added benefit of complete 
toolbox support. Not only that, but the instruction set is very 
impressive. There is even AppleTalk support built into the 
Basic! Only some nagging bugs keep this from being the front 


runner. 


' Menu/Window Deno 

' ZBASIC version 

' by Deve Kelly 

' ©1986 MacTutor 

' Zbasic configuration as follows- 
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' open sample window 
WINDOW 1,"",C100, 100)-(400,225),2 
GOSUB "Setupwindow" 
ON MENU GOSUB "menuevent" 
MENU ON 
"loop": 
GOTO "100p" 
"HandleAct":MENU STOP:MOUSE STOP 
ACT=DIALOG(@) 
IF ACT=5 THEN GOSUB "Setupwindow" 
MENU ON: MOUSE ON 
RETURN 
"menuevent" : 
menunumberzMENUC?) 
menu i tem=MENUC 1) : MENU 
ON menunumber GOSUB "menu1", "menu2", "nenu3" 
TURN 


"menu 1" : 
IF menuitem=1 THEN "Quit" 
RETURN 


"menu?" : 

' This is the Edit menu 

' use it for DA's only 

z = FN SYSTEMEDIT(menuitem+ 1) 


“menus” : 

LOCATE 3,1 

PRINT"You have selected menu item";menuitem 
RETURN 


"Setupwindow" : 
CLS 


TEXT 2, 12,1,8:' TEXT[font][, (size), [face], [mode 1] 
PRINT "MacTutor shows you how it works!" 

TEXT 2, 12,0,0 

LOCATE 5, 1:PRINT"ZBASIC Version 3.01 demo" 
Activity=0 


PCMac Basic Demo 

Our other Basic Compiler is shown below. The 
documentation is poor in comparison to Z Basic, especially in 
the area of the toolbox. Note that this Basic uses a resource 
file (not shown) and a built-in resource editor compatible with 
McAssembly for window and menu definitions. Note the use 
of line numbers instead of labels. Complete toolbox access 
and strong assembly compatibility at the source and object 
level make this product worth watching. 


1 REM Menu/Window Demo 
REM POMacBASIC version 
REM by Dave Kelly 


; dbl, sgl, float = 16,14, 12;default-I;Locate Y,X 
COORDINATE WINDOW: ' set to Macintosh window coord 
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REM 1986 MacTutor 
lg REM If Sample Menu is selected 
KEYC1) ON : ON KEYC1) GOSUB 3001 


KEY(2) ON : ON KEY(2) GOSUB 3902 
KEYC3) ON : ON KEY(3) GOSUB 3003 
20 GOSUB 2000 
REM IF File Menu is selected 
FILES MENU ON : ON FILES MENU GOSUB 1100 
REM IF Edit Menu is selected 
EDIT MENU ON : ON EDIT MENU GOSUB 1200 
ON WINDOW GOSUB 2000 
50 REM Infinite Loop 
GOTO 50 
1100  menuitem$-FILESC0) 
IF menuitem$-1 THEN 4000 :REM Quit was selected 
RETURN 


1200 REM This is the Edit menu 
REM use it for DA's only 
RETURN 


2000 CS 
SCREEN ®"New York", 12 
COLOR 10,0 
PRINT "MacTutor shows you how it works!" 
COLOR 2,9 
LOCATE 5, 1:PRINT"PCMacBASIC Version 1.68 demo" 
RETURN 


3001  menuitem$-1:G0TO 3010 
3002 menuitem%=2:G0TO 3010 
3003 i ID 3 10 
3010 LOCATE 3 
PRINT" You [^ selected menu item" ;menuitem% 
RETURN 
4000 END 
True Basic Demo 

This Basic has to be considered the most bug free and 
ready for sale Basic of the four. And it has a very good manual 
from an instructional point of view. From a reference point of 
view, the Z BAsic manual is much better. Note that this Basic 
is almost pure toolbox. In fact, the following program could 
be easily translated into Pascal or Assembly because it is 
practically ALL toolbox programming. At first this might 
seem a great asset. And it would be if you got a pure object 
code file after all the detail of toolbox programming. But what 
you end up with is more work and less show, since it is 
interpreted. You might as well have started off in a compiled 
language if you going to have to deal with this kind of 
toolbox detail! On the plus side, this Basic has tremendous 


floating point support. It's accurate, fast, and supports matrix 
inversion and other math functions found only in HP 9836 
Basic. If this were a compiler, it would have to rate number 
one. 


! Menu/Window Deno 

! True Basic version 

| by Dave Kelly 

! ©1986 MacTutor 

! Trap calls highlited in bold 

LIBRARY ":Toolbox Libraries:menul ib*" 
LIBRARY ": Toolbox Libraries: window] ib*" 
LIBRARY "“: Toolbox Libraries:desk] ib*" 
LIBRARY ": Toolbox Libraries:event] ib*" 
LIBRARY ": Toolbox Libraries: quick] ibt" 
LIBRARY ": Toolbox Libraries:datalib*" 
LIBRARY “: Toolbox Libraries:maclib*" 
LIBRARY “: Toolbox Libraries: addr*" 
LIBRARY “: Toolbox Libraries: pass_mac*" 
LIBRARY "“: Toolbox Libraries:s trep*" 
LIBRARY ":Toolbox Libreries:r-trap*" 
LIBRARY ":Toolbox Libraries:tostring*" 
DECLARE DEF NIL$,POINTER$, screenBits$,bounds$ 
DECLARE DEF OpenDeskAcc, NewWindow$, SystemEdit 
DECLARE DEF MenuSelect 

DIM MyMenus$(1:4)  ! We have four menus 
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CALL TakeMac ! Teke control of the Mac 
CALL SetUpMenus ! Set up menus 

LET vel depo ==) 

LET doneF lag = ! initialize DO-UNTIL loop 

LET R$ = ert PE ! Get screen rect 

CALL SetRect(R$, 102, 100, 400,225) ! Set window rect 


LET myWindow$ = Newiindow$(NIL$, R$,"",-1,1, 
POINTER$C- D, ø, 0) 

CALL SetPort(nyWindow$) 

CALL Drewwindow 

! Main Event Loop 

DO 


CALL SystemTask 
CALL GetNextEvent(everyevent, theEvent$, eResult) 
IF eResult € Ø then 

CALL UnpackEvent( theEvent$, what, mess, 


when, where$, mod) 
SELECT CASE what ! Branch on event type 
CASE 1 ! Mouse down event 
CALL FindWindow(where$, whichWindow$, wResult) 
SELECT CASE wResult ! Branch on ‘location 
CASE 1 ! In menu bar 
LET mResult = MenuSelect(where$) 
CALL DoMenuCmResul1t) ! Act on menu 
CASE 2 ! In System window 
CALL SysteaClick(theEvent$, whichWindow$) 
CASE else 
END SELECT ! for mouse-down location 
CASE 6 ! Update event 
CALL Packb(w$, 1,32, mess) ! Extract window 
pointer 
CALL BeginUpdate(w$) ! Begin update 
CALL Drawwindow ! Update window 
CALL EndUpdate(w$) ! End update 
CASE else 
END SELECT 
END IF 


LOOP UNTIL doneFlag o Ø 

CALL DisposeWindow(myW indow$) 

CALL ClearMenuBar 

FOR i = Lbound(MyMenus$) TO Ubound(MyMenus$) 
CALL DisposeMenu(MyMenus$Ci >) 


NEXT i 
CALL GiveMac ! Return control to True Basic 
STOP ! al? done! ! 


SUB Drawwindow 
CALL TEXTFONT(2) 
CALL TEXTSIZEC 12) 
CALL TEXTFACEC 1) 
CALL TEXTMODE(O) 
CALL MOVETOC 19, 28) 
CALL DRAWSTRING(' MacTutor shows you how it works!") 
CALL TEXTFACEC2 
CALL MOVETOC 12, 1583 
CALL DRAWSTRING( "True BASIC Version 1.1 demo") 
END SUB 
SUB DoMenu(Ccode) 
! Replace with HiWort and LoWord 
CALL Packb(s$, 1,32,code) 
LET MenuNumber = Unpackb(s$, 1,- 16) 
LET MenuIten = Unpackb(s$, 17,- 16) 
SELECT CASE MenuNumber 
CASE 1 ! Apple Menu 
CALL GetI tem(MyMenus$¢ 12, MenuItem,neme$) 
LET mrefNum = OpenDeskAcc(nane$) ! Open da 
CALL SetPort(mywindow$) ! Restore current grafport 


CASE 2 ! File Menu 
LET doneFlag = -1 ! Set flag to quit 

CASE 3 ! Edit Menu 
LET z = SystemEdit(Menuitemn* 1) 

CASE 4 ! Sample Menu 


CALL MOVETOC 10,50) 

LET textstringk = "You have selected menu item " & 
STR$Cmenui tem) 

CALL DRAWSTRINGCtextstr ing$) 
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CASE else 

END SELECT 

CALL HiliteMenuC?) 
SUB 


SUB SetUpMenus 
DECLARE DEF NewMenu$ 
LET MyMenus$C1) = NewMenu$C 1, chr$C205) 
CALL AddResMenuCMyMenus$C 1), "DRVR") 
LET MyMenus$(2) = NewMenu$C2, "File") 
CALL (MyMenus$ C2), "Quit") 
LET MyMenus$(3) = NewMenu$(3, "Edit") 
CALL AppendMenu(MyMenus$(3), "Cut" ) 
CALL AppendMenuCMyMenus$ C3), "Copy" ) ! Copy command 
CALL AppendMenuCMyMenus$ C3), "Peste" ) ! Paste command 
LET MyMenus$(4) = NewMenu$(4, "Sample Menu") 
CALL AppendMenu(MyMenus$(4),"Item 1")  ! Menu item 1 
CALL AppendMenuCMyMenus$(4),"Item 2")  ! Menu item 2 
CALL AppendMenu(MyMenus$(4),"Item 3")  ! Menu item 3 
FOR i = Lbound(MyMenus$) to Ubound(MyMenus$) 
CALL InsertMenu(MyMenus$C i), 8) ! Insert each 
menu 


NEXT i 

CALL DrawMenuBar 
END SUB 
END 


! No Selection 


! unhighlight menu 


! Get file menu 
! Quit command 
! Get edit menu 
! Cut command 


! Drew in the menu bar 


Cursor User 


The following program was sent in a few months back. 


loop:GOTO loop 
checkmenu: 


menunumber=WENUCG) 
menu i tem=MENUC 1) : MENU 
ON menunumber GOSUB Control, LoadCursor 


RETURN 
Control: 
ON menuitem GOSUB QUIT 


: ‘Current Cursor (CC) 
IF menuitem=1 THEN ON menuitem GOSUB 
allcursors:RETURN 
MENU OFF 


CCIndexSzCmenuitem-2)*34 
SETCURSORCVARPTRCent ire$CCCIndex$ 22) 


count$- 1 
ERASE entire% ‘this feature lets us reload 
j DIM entireg(araysize%) ‘a new sequence of cursor files 
again: 
f i lename$=FILES$(1,"CURS") — '"CURS" for files created by 
IF filename$="" THEN exitload ' Dave Kelly's program 
OPEN filename$ FOR INPUT AS *1 


Thanks go to Don Fuller for sending this program. The 
program demonstates how to read the Cursor Editor data files. 
Cursor Editor appears on Source Code disk #3 from the Aug. 


FOR i= TO 33 
INPUT *1, entire£Cindex£) 
index%=count&+ i 


1985 issue of MacTutor. 

'Cursor User 

‘This program loads cursors mede by 
‘Dave Kelly's Basic School in the 
‘August 1985, MacTutor 

‘After loading the cursors, 

‘each cursor may be selected 

‘from the menu, thence displayed 

‘on the screen 

‘Copyright Dec. 1985, Don Fullmer 
WINDOW 1,"Cursors...",(2,45)-(5 10,348), 1 
WINDOW OUTPUT 1 

ereysize$-340 ‘Maximum of 10 cursors to load 
DIM entire&Caraysize$) 

FOR i=1 TO 5:MENU i,0,0,"":NEXT ‘clear menu bar 
MENU 1,9,1, "Control" 

MENU 1,1,1, "QUIT" 

MENU 2,0, 1, "Load Cursors" 

MENU 2,1, 1, "A11..." 

ON MENU GOSUB checkmenu 

MENU ON 
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NEXT 
CLOSE #1 
f Inm$=RIGHT$(f i lename$, LENCf i lename$ )-CINSTR( 


filename$, ":"))) 
MENU 2,0%+1, 1, f Inn$ 
count%=count%+34 
IF LENCfInm$) > 11 THEN f Inm$=LEFT$Cf Inm$, 11) 
PRINT USING "#88" ag; :PRINT " ";finm$, ‘keeping a 
visual 
IF a% MOD 3-0 THEN PRINT 
‘list of the files 
a%=a%+ 1 


IF a%=11 THEN exitload 
files... 

GOTO again 
exitload: 

RETURN 
QUIT: 


MENU RESET 
: 
INN. CLOSE 1 Ped 


‘maximum of 10 
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Basic School 
Random Access Files 


There are two types of data files that can be created and 
used by your MS Basic program: sequential files and random 
access files. Sequential files are used more often because they 
are easy to create, but random access files are more flexible and 
data can be located faster. A discussion of sequential file I/O 


operation begins on page 45 of your MS Basic manual (ver. 


2.0 or greater). Random Access File I/O starts on page 48. 
Before we begin our discussion of random access file I/O, I 
suggest that you refer to those pages. 

The purpose of this column is to help you develop an 
understanding of random access I/O and how to use it in your 
own programs. It is very easy to understand how data is 
structured in sequential files. It requires more work to 
organize a random access file. The organization of the random 
access file is up to you. I'll try to outline some steps you can 
use to help organize your file. 

First, you should decide just what data you have to store. 
For example, if you were setting up a mail list database you 
would need one field each for name, address, city-state, and 
zipcode. Next decide how many characters will be allowed for 
each field (25 for name, 30 for address, 25 for city-state, and 5 
for zipcode). The total length of an individual record would 
then be 85 characters. 

Now decide how many individual records you expect to 
have in the file. If you don't require too many records and 
don't expect to ever expand the file, a sequential file many be 
suitable. The is especially true if you have a lot of RAM to 
work with and a comparatively small data file. There are some 
advantages and disadvantages to using a sequential file this 
way. With a sequential file, all records are read into memory 
so the disk is only accessed once. The program can then 
operate on the data much faster than if it had to access the disk 
for each record. However, if the data had been changed at all, 
the entire file would have to be stored back to the disk or the 
changes would be lost. In the event of a power failure or 
some other system crash, a random access file would contain 
all the changes, but a sequential file would not. Generally as 
files get larger, they are better handled by random access 
methods. A large sequential file could take quite a bit of time 
Just to read and write to the disk. 

Next you should consider how you want to access each 
record of your random access file. You may want to be able to 
search for a name or sort the file by zip code. A long and 
tedious way to do this would be to read through each and every 
record until the desired record is found. If the user knows 
exactly which record to read then the access time may be 
reduced significantly. One way to do this would be to create 
an index file. For example, if you wanted to find a specific 
record and you know the contents of one of the fields, you 


390 


EN 


Dave Kelly 
MacTutor Editorial Board 


could look in the index file to find the matching field and 
record number. For a mail list database you might set up an 
index file containing all of the names and the record numbers 
corresponding to the names. Index files may be sequential or 
random access (for relation databases) but should contain as 
few fields as possible to optimize data access time. If the 
index is sequential it should be kept in memory and updated as 
the random file is updated. 


Sequential Index File 


Random Access File 
n = number of records 


Se) Record 1 
Recordnumber (1) 
Record 2 
recordnumber (n 
Record n 


Figure 1 


If indexes are used, some thought must be taken as to 
updating and changing the index file. If a record is to be 
deleted, you might want to delete the index, thus removing 
any reference to the random access file record. This leaves an 
available record for late addition of a new record (if you keep 
track of which records have been deleted). If your file isn't 
expected to change very much you may not mind the wasted 
space taken up by the deleted record. Ideally, you should keep 
track of the locations of deleted records so that they can be 
reused when new records are added. Another way to get rid of 
the wasted records (if you don't want to go to the trouble of 
keeping track of the deleted records) is to write a program to do 
"Garbage Collection". 

A "Garbage Collection" program reads all undeleted 
records and writes them to a new file. You only have to do 
"Garbage Collection" when a lot of records have been deleted 
and you need more space to add new records. "Garbage 
Collection" might be ok to use if it is automatically 
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Record 2 
Record 3 


<< Garbage 


Fig. 2 Garbage Collection 


performed (with no user intervention). It is NOT desirable for 
the user of your program to have to keep track of this kind of 
file handling (when to collect garbage and when not to). 

When a record is added to the datafile, a new index entry 
should be created and the new record should be added to the 
random access file (either as a new record or replacing a 
previously deleted record). If an existing record is edited and 
changed the index file should be updated accordingly. You 
may want to sort the index file before writing it to the disk. 
Be sure to save the index program before quiting the program. 

Now let's take a look at how the random access file is 
structured. When you open a file in basic, a buffer is allocated 
for each file opened. For random access files the buffer should 
be set equal to the length of one record ( the default buffer size 
is 128 bytes). It is through this buffer that basic reads and 
writes to the disk. To help you understand what a random 
access file "looks like", let's create a sample file to examine. 
The Random Access File program included with this column 
will create a sample random access file that we can analyze. It 
creates a random file named "Sample RA File" with a length 
of 64 bytes. One advantage of MS Basic random access files 
is that random access files require less room on the disk, since 
Basic stores them in a packed binary format. Sequential files 
are stored as a series of sequential ASCII characters. 

To facilitate the conversion of numbers to the packed 
binary format we must use the MKI$,MKS$,MKD$ 
commands. To unconvert the numbers we must use 
CVI,CVS,CVD commands. These are somewhat easy to 
remember if you think of the MK as MaKe and the CV as 
ConVert. Thus if we want to store an integer number we use 
MKIS$ to MaKe an Integer string and use CVI to ConVert 
the Integer back again. The sample file shows an example of 
how to use these MaKe and ConVert commands for integers, 
single precision and double precision numbers. 

As I already mentioned, when the file is opened a buffer is 
allocated (in this case the length of all the fields is 64). The 
fields that we want to use must be memory mapped to the 
buffer area. This is accomplished with the FIELD statement. 
You may use as many FIELD statements as you like, 
however, each field statement starts defining the fields starting 
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at the beginning of the buffer. If you define all your fields on 
one line (one FIELD statement) then you won't have any 
problem, but if you have more fields than you want to put in 
one statement then you will want to use a second FIELD 
Statement. The trick (which the manual does not show you 
how to do) is to define a dummy variable with the 
accumulative length of all the previous field statements before 
defining your next field. In the sample program the first 
FIELD statement defines three number fields with a total of 
14 bytes. (Integer fields are converted to 2 bytes, single 
precision to 4 bytes, and double precision to 8 bytes). In the 
second FIELD statement a dummy string is marking the first 
part of the buffer which has already been defined so that the 
next field will begin after the previously defined fields. If you 
didn't know to do this you could have some strange effects 
when you read your file back as the field definitions would 
overlap. 

The next important thing that the program must do is to 
put our data into the buffer so it can be written to a record on 
the disk. This is accomplished with the LSET or RSET 
statements.  LSET will left justify the string within the 
defined field length (a variable might be actually shorter than 
the field has available), The RSET statement will right 
justify the string within the field. Every field must be set into 
the buffer with one of these commands. You should use a 
different variable in defining the fields and setting into the 
buffer than you use to manipulate your data. Be sure that you 
don't use a defined field in an INPUT or LET type statement. 
This will redefine the location that the variable points to (we 
want it to put to the buffer area). If a record is read from the 
disk, all the fields defined in the buffer area will contain the 
data stored on the disk for that record. You only have to reset 
those fields that you want to change. All the rest of the fields 
will be left untouched until you read another record into the 
buffer or set a new value into the field. 

To store a record to disk use PUT [# ]filenumber [,record- 
number |. To read a record from the disk use GET [# 
]filenumber [,record-number ]. The PUT, GET statements 
read and write the entire record in the buffer. You use PUT 
after you use the MaKe string statements and use ConVert 
statements after using GET. You can find more information 
on PUT and GET in your Basic manual (pages 220 and 146). 
Run the sample program to create a random access file we can 
examine. 

The second program included with this column is a random 
access utility that I developed to analyze the data stored in a 
random access file. I have been saved from alot of problems 
with programs like this in the past. I have been able to repair 
damaged random access files and determine what buggy random 
programs were doing with utilities like this one. 

The utility program opens with a menu which will allow 
you to open your file. Choosing open from the File menu 
brings up the standard getfile dialog box from which you can 
choose the file you want to examine. (You should choose 
"sample RA File" for this example). Next, the program asks 
for the length of the random access file record. If you wrote 
the program you should have this available, however, if you 
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don't know what it is you can guess. The sample file is 64 
bytes so enter a 64 for the length (then click OK). 

The file menu now has made active a menu item named 
Edit in the File menu (this may be confusing - it is NOT the 
Edit menu). Selecting Edit from the File menu will bring up 
a prompt for the record number you want to read. Enter a'1' 
to read record number one (the sample file only has one record) 
(click OK). Next the record is read into the buffer and 
displayed on the screen. The first EDIT FIELD shown 
displays the file as it looks. Note that some of the ASCII 
characters are invisible and can't be seen in the EDIT 
FIELD. The second EDIT FIELD shows the equivalent 
ASCII representation of the record. Invisible characters can be 
seen (for example a '0' is a null character). Either of these two 
fields can be modified or examined as you like. 

The hardest thing to analyze is the numbers which have 
been converted to strings with the MaKe statements. To 
make this somewhat easier (though not foolproof) the program 
provides a way to convert your numbers from strings to 
numbers and numbers to strings to see how these 
ConVert/MaKe statements work. The third EDIT FIELD 
provides the way to enter the number or string to be converted. 
For example, enter a 5 in the field and select MKlI$(integer) 
Convert from the Convert menu. The integer 5 will be 
converted to the packed binary format string. Note that the 
first field stored by our sample file is '0, 5' which was the two 
byte string made from the integer 5 (see the sample program if 
you don't follow this). The converted string has been placed 
in the third EDIT FIELD. The characters there are invisible 
(0 and 5 ASCII do not print). If you select CVI(string) 
Convert (2-bytes) from the Convert menu, the string will be 
converted back to the integer equivalent and displayed. 

The rest is up to you as to what you want to do with the 
utility. It is possible to modify data in the random record by 
typing the change in one of the first two EDIT FIELDS. 
Then select the button at the top of the window to write the 
record. When you select 'OK', the EDIT FIELD which 
which is active (the EDIT FIELD which the cursor is 
blinking) will be stored in place of the record. It is possible 
to convert a number in the Convert EDIT FIELD then 
COPY the contents of the EDIT FIELD and PASTE it into 
the text in the first EDIT FIELD. It may be somewhat 
difficult to COPY/PASTE invisible characters (because you 
can't see them to select them) although it is possible. I 
recommend that you display the converted ASCII equivalent 
and enter the ASCII characters into the second EDIT FIELD 
and save the record to the disk. 

That's all there is on random access files. Hopefully the 
utility will help you to learn some things by experimentation 
about random access. Any questions may be directed to 
myself via MacTutor. 


' Random Access File 
' @MacTutor 1986 
' This program creates a sample Random Access File 


Integer%=5: Single!=32769!: Double#= 1234567898 


Title$-"MacTutor, The Macintosh Programming Journal" 
OPEN "Sample RA File" AS #1 LEN-64 
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FIELD *1,2 AS I$,4 AS S$,8 AS D$ 
FIELD *1, 14 AS Dunny$,50 AS T$ 


TEXTFACEC 1) 
PRINT "Our Variables are: 
Integer$-"; Integer£; "Single!z";Single! 
PRINT "Double#="; Double! 
PRINT "Title$=";Title$ 
TEXTFACECO ) 
WRIT: PRINT'We will now save them to record 1 (record 
lengthz64)." 
LSET I$=WKI§( Integer) 
LSET S$=MKS$(Single! ) 
LSET D$=MKD$(Doub1e*) 
LSET T$=Title$ 
PUT 51,1 
CLOSE *1 
PRINT"Now clear all variables... and print them:" 
Integer%=0 :Single!=0:Double*=0:Titleg="" 
TEXTFACEC 1) 
PRINT "Our Variables are: 
Integer$-"; Integer%; "Single!z";Single! 
PRINT “Double#=" Double 
PRINT "Title$-";Title$ 
TEXTFACECO ) 
PRINT "Now read them back again..." 
OPEN "Sample RA File" AS 81 LEN-64 
FIELD *1,2 AS 1$,4 AS S$,8 AS D$ , 50 AS T$ 
GET 31,1 
LET Integer%=CVICI$) 
LET Single!=CVS(S$) 
LET Double*tzCVDCD$ ) 
LET Title$-T$ 
PRINT"Now close the file and print them all..." 
CLOSE #1 
TEXTFACEC 1) 
PRINT "Our Variables are: 
Integer %="; Integer’; "Single!=";Single! 
PRINT"Double*=" ; Doublet 
PRINT "Title$=";Title$ 
TEXTFACEC? ) 
END 


' Professor Mac's Random Access Utility 
' @MacTutor 1986 
' By Dave Kelly 


OPTION BASE 1 

DEFINT a-z 

WINDOW 1,"",(2,252-C510,3355,3 
GOSUB WindowHeader 
Recordnumber= 1 


MENU 1,0, 1, "File" 
MENU .1, 1, 1, "Open" 
MENU 1,2,0,"Close" 
MENU 1,3,0, "Edit" 
MENU 1,4,1, "Quit" 
MENU 3,0,0,"" 
MENU 4,0,0," 
MENU 5,0,0,"" 


False-0: True= NOT False 
Fileopen = False 


ON MENU GOSUB MenuEvent 
MENU ON 


WaitForEvent: GOTO WaitForEvent 


MenuEvent : 
MenuNumber = MENUCO) 
MenuItem = MENUC 12: MENU 
ON MenuNumber GOSUB Fi lemenu, Edi tmenu, Convertmenu 
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Filemenu: RETURN 
ON MenuItem GOSUB OpenFile,CloseFile,FindRecord,Quititem 


CloseFile: 
Fileopen-False 
Editmenu: MENU 1,1,1 
RETURN MENU 1,2,0 
MENU 1,3,0 
WindowHeader : CLOSE *1 
TEXTFONT(2) : TEXTSIZEC 14): TEXTFACEC 1) IF MenuItem o4 THEN GOSUB WindowHeader 
LOCATE 1, 15:PRINT"Random Access Utility" RETURN 
TEXTSIZEC 12): TEXTFACEC2 ) 
TURN GetRecord: 
IF Recordnumber=9 THEN PRINT "Record # Ø does not 
Quititem: exist" :RETURN 
IF Fileopen = True THEN GOSUB CloseFile GET * 1, Recordnumber 
MENU RESET R$=Random$ 
WINDOW CLOSE 1 RETURN 
END 
StoreRecord: 
OpenF ile: LSET Randon$-R$ 
Filenane$-FILES& 1) PUT *! 1, Recordnumber 
IF Filename$-"" THEN GOSUB WindowHeader: RETURN RETURN 
LOCATE 4, 1:PRINT" Enter the length of your Random 
Access File:" FindRecord: 
GOSUB WindowHeader as 
EDIT FIELD 1," 128", (300, 48)-(€359,63), 1, 1 LOCATE 4, 1:PRINT"Enter Record Number to find:" 
BUTTON 1, 1, "0K", C315, 1302- C365, 180) EDIT FIELD 1, STRECRecordnumber ), (208, 482- (250,63), 1,1 
GOSUB Loop BUTTON 1, 1, "OK", C315, 1302-365, 180) 
Recordlength-VALCEDITSC 12) GOSUB Loop 
IF Recordlength »32767 OR Recordlength «20 THEN GOTO Recordnumber-VALCEDITSC 12) 
OpenF ile LOCATE 5,1 
BUTTON CLOSE 1 IF Recordnumber«1 OR Recordnumber > 16777215 THEN 
EDIT FIELD CLOSE 1:CLS PRINT "Number out of range":BEEP:FOR i=! 
OPEN Filename$ AS #1 LEN-Recordlength TO 100:NEXT:GOTO F indRecord 
FIELD *1,Recordiength AS Random$ GOSUB GetRecord 
EDIT FIELD CLOSE 1 
Setup: EditRecord: 
GOSUB WindowHeader MENU ON 
Fi leopen=True CLS:GOSUB WindowHeader 
MENU 1,1,0 BUTTON CLOSE 1 
MENU 1,2,1 GOSUB DecodeASCII 
MENU 1,3,1 PRINT "Current Record is *";Recordnumber 


Random Access Utility 


Current Record is * 1 © Write record after Edit 
hHücdTHazTutaer, The Macintosh Programming Journal 


0, 5, 71, 0, 1, 0, 65, 157, 111, 52, 84, 0, 0, O, 77, 97, 99, 84, 
117, 116, 111, 114, 44, 32, 84, 104, 101, 32, 77, 97, 99, 105, 110, 
116, 111, 115, 104, 32, 80, 114, 111, 103, 114, 97, 109, 109, 105, 
110, 103, 32, 74, 111, 117, 114, 110, 97, 108, 32, 32, 32, 32, 32, 
32, 32, 
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LOCATE 17,1:PRINT "Conversion string:" 
TEXTFONT(4) 
EDIT FIELD 3,"",( 18,288)-(99,295),2, 1 
EDIT FIELD 2; ,ASCIIS, (10, 130)- (485, 250), 1,1 
EDIT FIELD 1 R$, (10, 40)- (485, 125), 2,1 
TEXTFONT(2) 
BUTTON 1, 1, "OK" , 458, 255 )- (588, 385) 
BUTTON 2, y "Write record after Edit",(275,22)- 
(459,37),3: b2=False 
MENU 3,9, 1, "Convert" 
MENU 3, L 1) "CVICstring) Convert (2-bytes)" ‘Convert 2- 
byte string 
MENU 3,2,1,"CVSCstring) Convert (4-bytes)" ‘Convert 4- 
byte string 
MENU 3,3,1,"CVDCstring) Convert (8-bytes)" ‘Convert 8- 
byte string 
MENU 3,4, 1,"MKI$Cinteger) Convert" ‘Convert integer 
MENU 3, 5. L , MKS$Csingle-precision) Convert" ‘Convert 
single-precision 
MENU 3,6, 1, "MKD$Cdouble-precision) Convert" ‘Convert 
double-precision 
i=1 
EditLoop: 
d-DIALOGC£) 
IF d=1 THEN buttonpushed-DIALOG( 1): IF 
buttonpushed-1 THEN 
EditDone ELSE GOSUB Switch 
IF d=2 THEN i-DIALOGC2) 
IF d=6 AND i=1 THEN EditDone 
IF d=7 THEN i-Ci MOD 2)+1:EDIT FIELD i 
GOTO EditLoop 
EditDone: 
R$=EDIT$C 1) 
IF i-2 THEN ASCII$=EDIT$(2): GOSUB EncodeASCII 
IF b2 = True THEN GOSUB StoreRecord 
EDIT FIELD CLOSE 1 
EDIT FIELD CLOSE 2 
EDIT FIELD CLOSE 3 
BUTTON CLOSE 1:BUTTON CLOSE 2 
MENU 3,0,0,"" 
CLS: GOSUB WindowHeader 
RETURN 


Conver tmenu: 
x®8=FRE(O) 
MENU OFF: TEXTFONT(4) 
Conver t$=EDIT$(3) 
LOCATE 17, 18:PRINT STRING$(35," ") 
LOCATE 18, 18:PRINT STRING§(35," "):LOCATE 17, 18 
ON Menul ten GOSUB CVIconvert, CVSconvert, CVDconvert, 
MKI convert, MKSconvert, MKDconver t 
MENU ON: TEXTFONT(2) 
RETURN 


CVIconvert: 
IF LENCConver t$)<>2 THEN PRINT"Can't convert"; 
LENCConver t$); "bytes." : RETURN 
IntNumber%=CVI(Convert$) 
PRINT "CVIC" | CHRÉC342; Conver t$; CHR§(34); "="; IntNumber$ 
TURN 


CVSconvert: 
IF LENCConvert$)<>4 THEN PRINT"Can't convert"; 
LENCConver t$); "bytes. " : RETURN 
SingleNunber ! -CVSCConver t$) 


PRINT 
"CVSC" ; CHRÉC342; Conver t$; CHR$C34); "=";SingleNumber ! 
RETURN 


CVDconvert : 
IF LENCConvert$)<>8 THEN PRINT"Can't convert"; 
LENCConver t$); “bytes. " : RETURN 
Doub leNumber?tzCVDCConver t$) 
PRINT "CVDC";Convert$; "="; Doub ]leNumber® 
RETURN 
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MKI convert: 

IF VALCConver t$)<-32767 OR VALCConvert$2»32767 THEN 

INT "Number too big! ":RETURN 
IntNumber$-VALCConvert$ ) 
NewConvert$-MKI$CIntNumber$ ) 
EDIT FIELD 3 ,NewConvert$, (10,280)- «0, 295) 
PRINT "MKI$C" ;Convert$; ' Js ASCII: ' 
PRINT USING " 88s" ASCCHIDgCNewConser t$, 1, 12), 

ASC(MID$(NewConver t$, 2,1) 


MKSconvert: 
IF VALC(Conver t$)<-1. 18E-38 OR 
VALC Conver t$)»3.3999E+38 THEN 
PRINT "Number too big!":RETURN 
SingleNumber ! :VALCConver t$) 
NewConvert$-MKS$CS ingleNumber ! ) 
EDIT FIELD 3 ,NewConvert$, (10,280)- (90,295) 
PRINT "MKS$C" ;Convert$;' ‘Js ASCII: e 
PRINT USING " s". ; ASCCMIDSCNeConver t$, 1, 12), 
ASC(WID$(NewConver t$, 2,105; 
PRINT USING " t5" ;ASCCHIDSCNewConver t$, 3,1), 
ASC(MID$(NewConver t$, 4,1)) 


MKDconver t: 
IF VALCConver t$)<-2.23D-308 OR 
VALCConver t$)» 1. 789999D+3g8 
THEN PRINT "Number too big!" : RETURN 
DoubleNumbertiZVALCConver t$) 
NewConver t$-MKD$ Doub 1eNumber't ) 
EDIT FIELD 3 ,NewConvert$, (10,289)- (90,295) 
PRINT “MKD$ (x)= ASCII:' 
PRINT USING " s88". ; SCCHIDS NenConver t$, 1,12, 
ASC(MID$(NewConver t$, 2,10) 
PRINT USING " 15:5". ;ASCCMIDSCNewConver t$, 3,1», 
ASC(MID$(NewConver t$, 4,10) 
LOCATE 18,33 
PRINT USING " 888" ASCCMIDÉCNewConvert$,5, 1), 
ASC(MID$(NewConvert$, 6,125; 
PRINT USING " sss". ;ASCCHID$CNewConver t$, 7,1), 
ASC(MIDS(NewConver t$, 8,1)) 


Switch: 
b2-NOT b2 
IF b2=True THEN BUTTON 2,2 ELSE BUTTON 2,1 
RETURN 


Loop: 
d-DIALOGC2) 
IF d=1 THEN Done 
IF d=6 THEN Done 
GOTO Loop 

Done: 

RETURN 


DecodeASCII: 

ASCII$="" 

FOR i=1 TO Recordlength 
ASCIInun$-STRÉCASCCHIDÉCRÉ, i, 12224" , " 
IF LENCASCI Inum$)=2 THEN ASCI Inum$=ASCI Inum$ 
IF LENCASCI Inum$)=3 THEN ASCI Inum$=ASCI Inum$ 
ASCII$=ASCII$+ASCI Inum$ 

i 
RETURN 


EncodeASCII: 

R$-"":comnapositionsl 

FOR i=1 TO Recordlength 
commap lacez INSTRCcommepos i tion, ASCII$,",") 
ASCIInum$-MID$CASCII$,commeposition, commap lace- 1) 
commapos i t ion-commap lace* 1 

l RS=R$+CHRECVALCASCI Inum$ )) 

NEXT i 

RETURN 
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Basic Compiler Update News 


, MacTutor is keeping you up to date on the latest 
developments of the new Basic products that have been 
released. There are some new developments which you should 
be made aware of. Refer to the August 1986 MacTutor for the 
preliminary review of these products. The status (as of this 
time) of all of the products we have reviewed is: 


MS BASIC (version 2.10): Not a word. Rumors have it 
that Microsoft is making improvements, including the 
compiler. No word on when or what. 

PCMacBasic: Major Improvements are in the works. I 
have not yet seen an update. 

Softworks Basic: I don't know if any improvements are 
being made. 

True Basic: Improvements are in the works. 

ZBasic (version 3.02b) :  Zedcor, Inc. has corrected 
several of the bugs we spoke about in our review and already 
sent me an updated (beta) copy. (Thank you!) Specifically: 


Z-Basic Enhancements 


e Files can now be located in any folder by volume 


* The Directory command now works if you specify the 
pathname (volume) as DIR ZBASIC DISK:Z FOLDER: Z 
FILENAME. DIR 1 and DIR 2 did not work. The way it 
is right now you need to know the name (exact spelling) to 
do a directory command. 

* Eject 1 and Eject 2 now works 

* You can specify the volume for the filename you want to run 
with the run statement. RUN filename,vol % This 
means that you can now run any application from any HFS 
folder with the RUN statement. This is not documented in 
the version of the manual that I have. 

* The mouse clicks in window title bars now works properly. 
They didn't fix that for the edit menu in the ZBasic compiler 
program yet though. 

* The default window will not appear in your standalone 
application if you use the WINDOW OFF statement at the 
beginning of your program. 


Even more improvements/enhancements are in the works 
so keep watching here for update information. 
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Basic School 
On Fonts and Cursors 


Controlling the Cursor 


As I've always advocated in previous columns, whenever 
I write a program I try to make it look as much as possible 
like a commercial program. You know, like the ones you pay 
lots of money for. Hopefully, we can learn the little tricks 
that help to make our programs look professional. 

Have you ever wondered how to make your cursor behave 
the way that the cursor does in MacWrite or other 
applications? For example, notice when you move the cursor 
from the active region of a window and into the menu bar or 
scroll bars, the cursor changes to the default (ARROW) cursor. 
MS Basic allows you to change the cursor by using the 
INITCURSOR and SETCURSOR toolbox commands, 
however, MS Basic doesn't provide a way to tell when the 
cursor is moved into or out of windows. The closest thing it 
has is the WINDOWO or the MOUSE) functions. With 
the mouse functions you can read the location of the mouse at 
any given time. The window functions return the active 
window and the height and width of the window. What isn't 
given is the location of the window in relation to the entire 
screen. I suppose that with some playing around, one of you 
clever programmers out there could fudge your way around it. 
There is an easier way. 

Fortunately we can still rely on our CLR libraries for 
help in calling the Macintosh ROM routines that we need. 
(By the way, CLR Libraries are a must if you're using MS 
BASIC. Rumor has it that the Libraries will be supported by 
the yet to be announced/released MS BASIC Compiler). 
There is one simple Quickdraw toolbox call (via ToolLib) 
which makes it easy to change our cursor when it crosses 
outside of the active region of our window. A demonstration 
of how this is accomplished is given in the Loop routine of 
this month's sample programs (there are two versions, one 
MSBASIC, the other ZBasic). 


Change the Cursor! 
loop: 
Wxc=WINDOW(2): Wy-WINDOWC3) 
SetRect! Rect(02,0,0, Wx, Wy 
x-MOUSE(0 ) :PtC 12-MOUSEC D): PLCO2-MOUSEC2) 
PtInRect! PtCOD, RectCOD, Result 
IF Result=False THEN INITCURSOR ELSE changecursor! 1 
GOTO loop 


The routine can be explained as follows: First the 
window width Wx and window height Wy are found with the 
window functions. These will be our reference. MS Basic 
sets the grafport (the output path) to the active window. We 
want to use the boundaries of this window to determine if the 
cursor should be an arrow or an insertion cursor. Next we 
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define a rectangle which is the same size as the current active 
region of the window. The width and height returned by the 
window functions give the coordinates of the active part of the 
window. Next we record the mouse position with the 
MOUSE functions. The variable Pt( will hold the 
horizontal and vertical point on the screen which the cursor 
points to. In the next statement we test to see if the point 
where the cursor is located is inside the rectangle (the active 
region) or not. If it is inside then we set the cursor to the 
insertion cursor (using the ChangeCursor statement from 
ToolLib) or else we set the initialize the cursor as the arrow 
cursor. 

The concept behind this is simple yet there are probably 
some of you that didn't know it could be done with MS 
BASIC. For ZBasic the procedure and concept is the same, 
but the syntax is slightly different. 

Well, so much for changing the cursor. 


Word Processing in Basic? 


What about other things that we've seen in the 
commercial programs that we would like to mimic in BASIC? 
How about a text editor? With all the text processing power 
that the Macintosh has, this is still a weak area when it comes 
to BASIC. A decent text editor program cannot be written in 
MSBASIC at this time. I mean the type with editing of text 
just like in MacWrite. We need more access to the toolbox. 
We could try using the EDIT FIELD statement to generate a 
large text field to type into, but this still doesn't give us 
enough control to check the text being typed in on the 
keyboard. When using default text in an EDIT FIELD 
statement in either ZBasic or MS BASIC, the text appears 
selected within the Edit field. This is not desirable in a text 
editor application, especially if text is continually added to the 
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Edit Field as characters are typed (if monitoring the keypresses 
were possible in an edit field). In MS BASIC we would have 
to monitor each and every character being typed (via 
INKEY$) and keep track of all the cursor locations and 
mouse clicks in a brute force manner. I dunno, maybe that's 
how word processors like MacWrite are written. Anyway, in 
BASIC that method would seem to be extremely tedious. 
Count MS BASIC out for that sort of processing. ZBasic 
version 3.02 which will soon be released will now allow you 
to poll the keyboard via events passed through the DIALOG 
statements. This fix was necessary to poll the keyboard when 
menus or other events were active. See the Basic update 
section at the end of this column to see what some of the 
improvements are in version 3.02. I have not yet had a chance 
to test out this improvement. 


Fonts We Can Do! 


Here's another one for you: How does MacWrite get all 
the Font names from the system file into a menu? Also how 
does it know what size of font is really available? Using 
Toolbox calls, the answer to this is really trivial. However, 
for Basic programmers, the answer is not so simple. The new 
libraries given in the JUNE 1986 MacTutor give us a possible 
way to do this. I have to admit though, the Toolbox routine 
that I really wanted to use, ADDRESMENU, was not 
available even with CLR Libraries. I've been told that there 
are other routines in the works that are soon to be released. 
Both ZBasic and MS BASIC with CLR Libraries would not 
allow me to use the ADDRESMENU Toolbox call. This call 
takes the type of resource like FONT and adds all the names of 
the fonts into items in a menu from the open resource file. 
Obviously this would be a quick way to build a font menu! 
The ZBasic manual includes ADDRESMENU on the list of 
Toolbox calls, however, the ZBasic event handling doesn't 
know it is even there. I wonder what the menu manager 
toolbox calls are good for with ZBasic anyway, since you can't 
mix ZBasic menu statmements with toolbox menu 
statements. This brings us to the subject of bugs... 


ZBasic Goofed on Events 
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The reason that toolbox menu calls and ZBasic menu 
Statements cannot be mixed is that ZBasic does a 
GetNextEvent at the beginning of each statement in the 
program. The result of this effect is to create problems if you 
are trying to implement a toolbox event loop. For one thing, 
it affects menu bar selection. If you select multiple menu 
items in rapid succession in our ZBAsic sample, before each 
item can execute, you will get a system crash. Thus menus 
can never be bullet proof. This bug is related to the problem 
of getting events because the event loop is intimately 
connected with the menu manager. Another problem is that 
menu selection is very slow as this month's example shows. 
If you change the font and then select from the file menu 
quickly, the desired font will not display because the file item 
was chosen before the font item finished executing 
Theoretically this can't happen on the Mac, and doesn't in MS 
Basic, but since ZBasic is calling GetNextEvent all the time, 
events can happen out of order, resulting in strange behavior. 
There may be many more ZBasic bugs which turn out to be 
related to this problem of how ZBasic handles events. 
Although the manual suggests that virtually every toolbox 
call is available from ZBasic, some of them don't work or are 
not implemented in the language and don't do anything when 
used, like ADDRESMENU. There is no way to determine 
which ones work and which don't short of trying them all. 


Fonts, Menus & ZBasic 


The method for determining what fonts are available on 
your system when using ZBASIC is found on page D-55 of 
the third edition of the ZBASIC manual. The font names are 
read one at a time in a loop using GETFONTNAME and 
stored away. Our sample program stores away the value of the 
font number and the font name in the arrays Font$() and 
Font(). The application font (#1) is skipped because it is the 
same as the Geneva font. (#3). Now that the font names are 
found, the font sizes are determined as needed using the 
REALFONT toolbox statement. Each time the font menu is 
selected a check mark is placed by the correct item in the font 
menu and the size menu is redrawn. Actually, the size menu 
is re-created (from scratch) each time. Here we have another 
ZBasic bug. It seems that the META characters don't work 
right when re-programming a menu item. They do work fine 
the first time the menu is created (or if it is recreated from 
scratch with the new changes made). The entire menu has to 
be re-created though. This is one reason the menu selection in 
our sample is so slow. 


Changing Font and Size 


In this month's sample program the items selected in the 
File menu (except for Quit) will print in the program window 
and in the selected font and size. The text font and size is 
changed in the ZBasic program with the TEXT statement. 
With the TEXT statement you may change font, size, face and 
mode in a single statement. The manual states that 'you may 
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also use the text commands of quickdraw'. However, if you 
substitute TEXTFONT and TEXTSIZE statements in the 
sample Basic program, the proper TEXTFONT and 
TEXTSIZE will not print. Another ZBasic bug? Until this 
problem is fixed I recommend that you always use the TEXT 
statement for changing fonts, sizes, etc. 


Back to MS Basic 


In MSBasic reading the Font menu is just a bit harder. 


than with ZBasic. First we have to be sure that the system 
resources are available. MSBasic's HFS problems may cause 
some difficulty here. Use the pathname for your System File 
(via System Folder) to specify exactly where the System File 
is located. Next we use GETINDRES to get a handle for each 
resource with the type "FONT". Then with GETRESINFO 
we can get the FONT names and ID# and store them away. 
Note that ID# is returned and not font numbers. Divide the 
font ID# by 128 to get the font number. Now that we have 
the font number and name just like we did in the ZBasic 
program, we can use REALFONT to see what sizes are 
. available. The proper sizes are shown in outline mode (via 
SETITEMSTYLE) in the size menu. (Note that the Size menu 
did not have to be redrawn from scratch to get the menu 
formatting to change!). 

In both sample programs a 'Style' menu could have been 
easily added. I'll leave that to you. The next step is adding a 
means to edit text in the window. This will have to be 
covered when that capability is adequately provided. Note that 
the MS Basic program requires the following CLR libraries... 
from  ToolLib: ChangeCursor, GetIndRes, GetResInfo, 
SetRect, PtInRect, OpenResFile.. from  MathStatLib: 
SortString.... from NewLibraries (see June 86 MacTutor): 
SetItemStyle. 


BASIC UPDATE 


Here is this month's report on the new BASICS recently 
released: 

MS BASIC: Still no word on the release of the 
compiler, however Dave Smith was able to get a peek at the 
compiler while at the Boston show last month. The compiler 
will require you to create your programs via the MS Basic 
interpreter. The compiler is supposed to be entirely 
compatible with CLR libraries. The interpreter is also being 
updated(???) but the release date is still a Microsoft secret. 

ZBASIC: I just received a new beta copy of version 
3.02. which includes the following additions/corrections: 
¢ Zoom in and Zoom out can now be detected with 

DIALOG(8) and DIALOG(9). 

e While edit fields are active the DIALOG statements will 
respond to SHIFT TAB events, Mac Plus up,down, left, 
right and clear keys. 

e Keypresses are now returned with DIALOG(16). This 
replaces INKEY$ during event trapping. 

e Enter or Return works for edit fields 

e Add +256 to window type to disable Go-Away box, add +9 
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for zoom box, add +16-23 for rounded corners on windows. 
Negative numbered windows for modal dialog windows. 

* HFS compatibility: The DIR command is fixed... DIR: 
ROOT:FOLDER:FOLDER...:FILENAME. The EJECT 
command now works. FILES$ now returns path names. 

* Edit menu may now be disabled. 

+ New SHUTDOWN statement. 

e Auto repeat SCROLL BUTTON. 

* Various bug fixes too numerous to mention. More items 
will be fixed in the final release version. 


Be assured that Zedcor is working hard to fix bugs, etc. 
If you know of any, please let them know. ZBasic still has 
great potential to become a significant development product on 
the Macintosh. 

PCMacBasic: Improvements on this have not yet been 
released although there have been improvements to the 
packaging of the product. The manual will soon be revised 
along with big improvements of the compiler to make it more 
HFS competible (the language already is HFS compatible). 
Toolbox documentation (a must!!) is being worked on. By the 
way, if you don't like the funny block cursor appearing when 
quitting the PCMacBasic programs you create, you can hide 
the cursor with the following statement: LOCATE 1,1,1,1,1 . 
Place it somewhere before the end of the program and the 
cursor will be hidden before the program terminates. 

True BASIC: They have revised their pricing of their 
runtime package from $500 to $150! [Thanks to Dave Kelly 
for this concession. -Ed.] Yes, that means to create your own 
applications you have to invest about $300. You may then 
create applications for your own non-commercial use. A 
commercial license is another $350. If you don't like this 
policy, why not drop them a line. Realize however, that this 
pricing is still not that much different from the pricing of the 
MS Basic interpreter + compiler (although we don't know 
what the exact price will be). I've received copies of the True 
Basic 3-dimensional Graphics library (nice package) and 
Sorting/Searching and Advanced String Library. I may 
comment on these at a later date if I find that the runtime 
package is acceptable. I have not yet seen the runtime 
package. 


' FONT SAMPLE DEMO 1 

" MacTutor® 1986 

' By Dave Kelly 

"MS BASIC 2.18 Requires CLR Libraries 


DEFINT A-z 

LIBRARY "Samplelib" 

filerefnum$-0 

openresf ile! "Microsoft BASIC 2. 18:System 
Folder:System", filerefnum$ 

changecursor! 4 

DIM Font( 127), Font$C1272, CheckC1272, PtCD, RectC3) 
Sizecheck(6) 

hand!=9: id%=8: type$- "FONT" :A$="" : x8=0 

fontstyle9-0:fontstyle10-0:fontstyle 12-0 

fontstyle14-0:fontstyle18-0:fontstyle24-0 

Resul t= 

X 1=58 : Y 1= 130 :X2=468 : Y22240 


é 
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False=0:True=NOT False 


MENU 1,0, 1, "File" 
MENU 1, 1, 1, "New" 
MENU 1,2, 1, "Open" 
MENU 1,3, 1, "Close" 
MENU 1,4, 1, "Save" 
MENU 1,5, 1, "Save As..." 
MENU 1,6,1, "Quit" 
MENU 3,0, 1, "Font" 
MENU 4,0, 1, "Size" 
MENU 5,0,0, "" 
GetFonts: 

ON ERROR GOTO 9200 
I=] 


FOR x3-0 TO 127 
GetIndRes! "FONT", x% hand! 
GetResInfo! hand!, id, type$, A$ 


IF LENCA$) THEN Font$C1)=A$:Font(1)=idS: Is1*1:A$2"" :idgs0 


10 NEXT x% 

ON ERROR GOTO g 

NumberofFonts=I- 1 

SortString! NumberofFonts, Font$¢ 1), Font¢ 1) 

FOR J=1 TO NumberofFonts 

IF Font$(J)="Geneva" THEN Check(J)=2 ELSE Check(u)=1 
IF Font$CJ)="Geneva" THEN g-Font(I2/128 

MENU 3,J,Check(J), Font$(u) 

NEXT J 


REALFONT! g,9,fontstyle9 
REALFONT! g, 18,fontstyle 10 
REALFONT! g, 12, fontstyle 12 
REALFONT! g, 14,fontstyle 14 
REALFONT! g, 18, fontstyle 18 
REALFONT! g,24,fontstyle24 
FOR J=1 TO 6 
SizecheckCJ251 

NEXT J 

Sizecheck(3)=2 

GOSUB Fontsizemenu 
TEXTFONT (2) 

TEXTSIZE (12) 

ON n GOSUB menuevent 


INITCURSOR 
loop: 
Wx-WINDOWC2) :Wy-WINDOWC3) 
SetRect! Rect(02,0,0, Wx, Wy 
x-MOUSEC2) :P tC 12-MOUSEC 12: Pt CO )-MOUSE(2) 
PtInRect! Pt(O),Rect(8),Result 
IF Result=False THEN INITCURSOR ELSE changecursor! 1 
GOTO loop 
Fontsizemenu: 
OFF 


Sizecheck(1),"9 Point” :SetItemStyle! 4, 1,8 
Sizecheck(2),"18 Point":SetItemStyle! 4,2 
Sizecheck(3),"12 Point":SetItemStyle! 4,3 
Sizecheck(4),"14 Point":SetItemStyle! 4,4 
5 
6 
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,9, 9izecheck(52,"18 Point":SetItemStyle! 4, 0 
MENU 4,6,Sizecheck(6),"24 Point":SetItenStyle! 4, 0 
IF fontstyle9 = True THEN SetItemStyle! 4, 1,8 
True THEN SetItemStyle! 4,2,8 

True THEN SetItemStyle! 4,3,8 

True THEN SetItemStyle! 4, 


4,8 
True THEN SetItemStyle! 4,5,8 
True THEN SetItemStyle! 4,6,8 


n] 
“i 
— 
o 
2 
eT 
” 
eT 
€C 
ond 
(c 
[ml 
E 
"n "m u m a 


IF fontstyle24 
MENU ON 


RETURN 

nenuevent : 

Menunumber = MENUCO) 

Menuitem = MENUC 1) 

MENU OFF : MENU 

ON Menunumber GOSUB File, Editmenu, Font, Size 
MENU ON 


RETURN 


File: 
ON Menuitem GOSUB 
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New i tem, Openitem,Closei tem, Saveitem, SaveAs, Quit 
RETURN 

Editmenu: 

RETURN 


Font: 

FOR J=1 TO NumberofFonts 
CheckCJ251 

MENU 3, J, CheckCJ) 

NEXT J 


CheckCMenuitem)22 

MENU 3,Menuitem, CheckCMenuitem) 
fontnum=Font(Menui tem)/ 128 
REALFONT! fontnum,9,fontstyle9 
REALFONT! fontnum, 10, fontstule 10 
REALFONT! fontnum, 12, fontstyle12 
REALFONT! fontnum, 14,fontstyle14 
REALFONT! fontnum, 18,fontstyle18 
REALFONT! fontnum, 24, fontstyle24 
GOSUB Fontsizemenu 

CALL TEXTFONT (Font(Menuitem)/128):' Font # is id&/128 
RETURN 


Size: 

FOR J=1 TO 6 
SizecheckCJ2- 1: MENU 4,J,1 
NEXT J 


Sizecheck(Menuitem)= 2 

MENU 4,Menui tem, 2 

IF Menuitem=1 THEN TEXTSIZE (9) 
IF Menuitem=2 THEN TEXTSIZE (10) 
IF Menuitem=3 THEN TEXTSIZE (12) 
IF Menuitem=4 THEN TEXTSIZE (14) 
IF Menuitem=5 THEN TEXTSIZE (18) 
IF Menuitem=6 THEN TEXTSIZE (24) 
RETURN 


Newitem: 
PRINT "New Selected" 
RETURN 


Openitem: 
PRINT "Open Selected" 
RETURN 


Closeitem: 

PRINT "Close Selected" 
RETURN 

Save item: 

PRINT "Save Selected" 
RETURN 


SaveAs: 
PRINT "SaveAs Selected" 
RETURN 


Quit: 
MENU RESET 


END 

9009 changecursor! 4 
RESUME 19 
BEEP:PRINT "OOPS" 


REM FONT SAMPLE DEMO 2 

REM MacTutor 1986 

REM By Deve Kelly 

REM ZBASIC configuration: Convert to Uppercase, Space 
Req'd, Locate Y,X 


Default variable type = I 

WINDOW OFF 

COORDINATE WINDOW 

DEF MOUSE= 1 

DIM Font(20),Font$(20), CheckC20), PtC D, Rect C32, Sizecheck(6) 

X1-50:Y12130:X224 10: Y2=249 

WINDOW 1, "Untitled", CX1,Y 12- (X2, Y22,265:REM Uses Zoom 
Window with no close box 

MENU 1,0, 1, "File" 
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CALL GETFONTNAMECØ, A$) 

IF LENCA$) THEN Font$C1)=A$:Font(1)=0: I=I+1 

FOR X=2 TO 127 

CALL GETFONTNAMECX, A$) 

IF LENCA$) THEN Font$C1)=A$:Font(I =X: I=I+! 

NEXT X 

NumberofFonts=I-1 

FOR J=1 TO NumberofFonts 

IF FontCJ2-3 THEN Check(J)=2 ELSE Check(J)=1 

MENU 3,J,Check(J), Font$Cu) 

NEXT J 

Fontstyle9 = FN REALFONT(3,9) 

Fontstyle1®@ = FN REALFONTC3, 18) 

Fontstyle12 = FN REALFONTC3, 12) 

Fontstyle14 = FN REALFONTC3, 14) 

Fontstyle18 = FN REALFONTC3, 18) 

Fontstyle24 = FN REALFONTC3, 24) 

FOR J=1 TO 6 

Sizecheck(J)=1 

NEXT J 

Sizecheck(3)=2 

GOSUB "Fontsizemenu" 

TEXT 3, 12 

ON MENU GOSUB "menuevent” 

MENU ON 

"loop": 

Wx=WINDOW(2) :Wy-WINDOWC3) 

Rect(0)-0:RectC1220:Rect(2)-Wx :Rect(3)=Wy 

X-MOUSECO) :PtCO )-MOUSEC 12 :P t C 1)=MOQUSE(2) 

Result = FN PTINRECTCPtCOD, RectC0)) 

IF Result-0 THEN CURSOR=0 ELSE CURSOR = 1! 

GOTO "loop" 

“Fontsizemenu" : 

MENU OFF 

MENU 4,9,1,"Size" 

IF Fontstyle9 = 1 THEN MENU 4, Il, SizecheckC 12, " «09 Point" 
ELSE MENU 4,1, SizecheckC D, "9 
Point" 

IF Fontstyle 10 = 1 THEN MENU 4,2,Sizecheck(2), "«019 
Point" ELSE MENU 
4,2,Sizecheck(2),"18 Point" 

IF Fontstyle12 = 1 THEN MENU 4,3,Sizecheck(3), "<0 12 
Point" ELSE MENU 
4,3, Sizecheck(3)2,"12 Point" 

IF Fontstylel4 = 1 THEN MENU 4,4,SizecheckC4), " «014 
Point" ELSE MENU 
4,4, Sizecheck(4),"14 Point" 

IF Fontstyle18 = 1 THEN MENU 4,5,Sizecheck(52), "«018 
Point" ELSE MENU 
4,5,Sizecheck(5),"18 P 

IF Fontstyle24 = 1 THEN MENU 4 
Point" ELSE MENU 


oint" 
,6,Sizecheck(6), " «024 
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4,6,Sizecheck(6),"24 Point" 
MENU ON 
RETURN 
"nenuevent" : 
Menunumber = MENUC?) 
Menuitem = MENUC 1) 
MENU: MENU OFF 
ON Menunumber GOSUB "File", "Edit", "Font", "Size" 
MENU ON 


RETURN 
"File": 
ON Menuitem GOSUB "New", "Open", "Close", "Save", "SaveAs" , "Quit" 
RETURN 


"Edit": 


"Font": 

FOR J=1 TO NumberofFonts 
Check(J)=1 

MENU 3,J, CheckCJD 

NEXT J 


CheckCMenuitem222 

MENU 3,Menui tem, Check(Menui tem) 

Fontstyle9 = FN REALFONTCFont(Menui tem), 9) 
Fontstyle 10 = FN REALFONTCFont(Menui tem), 10) 
Fontstylei2 = FN REALFONTCFont(Menui tem), 12) 
Fontstyle14 = FN REALFONTCFontCMenui tem), 14) 
Fontstyle 18 = FN REALFONTCFont(Menui tem), 18) 
Fontstyle24 = FN REALFONTCFont(Menui tem), 24) 
GOSUB “Fontsizemenu" 

TEXT Font(Menui tem) 

RETURN 


"Size": 

FOR J=1 TO 6 
Sizecheck(J)=1:MENU 4,J, 1 
NEXT J 


Sizecheck(Menuitem)= 2 

MENU 4, Menuitem, 2 

IF Menuitem=1 THEN TEXT , 9 
IF Menuitem=2 THEN TEXT , 10 
IF Menuitem-3 THEN TEXT , 12 
IF Menuitem-4 THEN TEXT , 14 
IF Menuitem-5 THEN TEXT , 18 
IF Menuitem-6 THEN TEXT ,24 
RETURN 


"New" : 
PRINT "New Selected" 
RETURN 
"Open": 
PRINT "Open Selected" 
RETURN 


"Close": 
PRINT "Close Selected" 
RETURN 


"Save": 
PRINT "Save Selected" 
RETURN 


"SaveAs": 

PRINT "SeveAs Selected" 

cube ad! 
"Quit": à 
MENU RESET P» 
END AER 
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Using the Segment Manager from Basic 


This month we'll discuss Macintosh memory management 
(part 2, part 1 was discussed back in the June 1985 MacTutor). 
While the information back in June 1985 is still valid, there 
are some other (new?) considerations that I haven't mentioned 
yet. If you have the June '85 MacTutor go back and review 
that information as it will be useful here as we talk about it 
some more. It would also be helpful to read Inside Macintosh 

Vol. I chapter 3 on Memory Management and Vol II chapter 
2 on the Segment Loader. 

Now that we have as much memory available as we ever 
dreamed we might have (remember when it was so great to 
have 16K RAM?), we need to talk about the best ways to 
make use of it. In review, please recall that the key to 
memory management in MS Basic is the CLEAR statement. 
Even on a Macintosh Plus you should use CLEAR to make 
the best use of the available memory. The following 
procedure will help you to quickly set up the memory 
configuration: 

1. Load your program and before running it type PRINT 
FRE(0) in the command window to determine the amount of 
memory used by your program listing. Record this number 
for later use. 

2. Run the program. The intent here is to determine the 
amount of memory that your variables need. For some 
programs you may not be able to run enough of the program 
to declare all of the variables. In that case you may have to do 
some rough guessing here. Either after running your program 
or sometime during the program (this may be more 
convenient) you should print FRE(0) again. The difference 
between this number and the number you recorded in step 1 
above is the amount of memory allocated to the data segment 
that is used for your variables. (FRE(-1) returns the number 
of bytes not used in the heap; FRE(-2) returns the number of 
bytes in the stack that have not been used; you may use these 
if it will help you). 

3. Now it's time to guess. Try to decide if the program 
will ever need more memory than this in the future. If you 
need to increase the program size later or allocate more 
variables you will need to allow some space for this. If you 
are not sure you may want to just add 20% or so more 
memory to the length of the program. Whatever you decide 
here will be your data segment memory. 

4. Now, if your program uses any Macintosh resources 
you will need to figure out how much of the heap to use. If 
you have extra memory like on the Mac plus it never hurts to 
have extra heap space. In fact, the heap may be more heavily 
used than the data segment depending on how many controls, 
or windows, etc. you may be using. Keep in mind also that if 
any desk accessories are opened they will need some heap 
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é File Segments 


iI Segment Sample 

Message$ = O Therefore...Data file(s) should be loaded 
Count® = 1 file(s) have been passed to this application 
Filenames are: 
Name Vol 
-32717 


Type 

egment DATA DATA 
his is part of the main segment 
pathis is part of the 1st segment 
eiThis is part of the 2nd segment 
This is part of the 3rd segment 


eiMemory = 1435060 


Fig. 1 Output of our Segment Program 


space of their own. By printing FRE(-2) it will show the 
heap memory allocation. If you print FRE(-2) before running 
the program you will know the amount of heap available to 
the program. After the program is run and resources are 
loaded, the amount of heap will decrease. You need to know 
the difference between the FRE(-2) before and after running 
the program. Record this number. 

5. Now you need to calculate the stack-size to use in the 
CLEAR statement. Many times it is not even necessary to 
change the data segment (leave it as large as the memory you 
have left). The number to use for the stack-size is calculated 
by stack-size = Total Ram - (data-segment-size + heap-size). 


Now how do you know when you need to adjust the 
memory allocation? Ans: Anytime that you notice an unusual 
amount of disk activity, especially just before displaying 
controls (edit fields, buttons, menus, windows etc.). It doesn't 
matter if you have a Mac Plus or not, if you don't adjust your 
memory properly, then the memory will not be used 
efficiently. In order to remain compatible with the 512K & 
128K Mac, the heap and stack default sizes are the same on the 
Mac plus. This may explain why so many Mac programs 
need to read the disk so often even though you may think you 
have a lot of memory (1Meg really is plenty for Basic!!). 
Good memory management planning can improve your 
program tremendously. Another thing to keep in mind is that 
once the CLEAR statement has been used to change the 
memory allocation it will remain that way for the next 
program that you load into memory. A second CLEAR 
statement will not reallocate the memory properly. It is best 
to quit to the finder and start all over unless the new program 
uses the same memory configuration. 

So much for MS Basic memory management. The 
comments above in addition to those in the June '85 MacTutor 
should give you all you need to handle most of your memory 
management. Memory management in other languages is 
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handled through use of the Segment Loader. Access to the 
Segment Loader is not provided in MS Basic. ZBasic 
provides the SEGMENT and SEGMENT RETURN 
statements which use the Segment Loader. We'll talk about 
those in a moment. First a few words about the Segment 
Loader. The Segment Loader allows you to divide up the code 
of your application into several parts. When the Finder starts 
up your application the Segment Loader is called to load in the 
main segment of your program. Other segments are loaded in 
automatically as needed. After a segment is no longer needed, 
your application can call the segment loader to make the 
segment purgable. This way if you have only a small amount 
of memory available you may still run a large program. The 
maximum size of a segment is 32K. Any code that is not 
used often may be in a separate segment so that it may be 
swapped in whenever it is needed. Another function of the 
Segment Loader is in supplying information from the Finder. 

Your ZBasic code will be compiled into code segments 
(resources of type 'CODE) automatically, no matter if you use 
the SEGMENT statements or not. When the code reaches a 
length of about 28K the segment will end and the next 
segment will be loaded. The SEGMENT RETURN 
statement marks the end of the CODE segment and returns to 
the calling routine (cannot be called from the same segment). 
You should arrange your application such that a segment 
consists of a subroutine. The routines you decide to separate 
into segments preferably should be routines which are only 
used occasionally (example: print routines). 

The following example program demonstrates how to 
"segmentize" your programs. However, because the segments 
in the example are small (less than 100 bytes), the segment 
memory swapping is virtually non-existent on a Macintosh 
plus (and probably all the other size Macs too!). If you really 
want to try this out, you'll have to write some larger CODE 
segments and run on a smaller Mac. You can check the 
segment sizes by choosing the COMPILE option of the 
ZBasic command menu. The sizes of the segments will be 
displayed. The remaining memory can be found with the 
MEM(-1) function. MEM(-1) returns the maximum amount 
of available memory for the program and variables. 

Another part of the Segment Loader is supported by 
ZBasic with the FINDERINFO function. The 
FINDERINFO function returns information to your 
application which tells the application how the application 
was selected from the Finder. The function returns variables 
with the number of files selected, the name of the files and 
volume number, and a message variable indicating if the file 
should be loaded or printed. This way the files may be 
printed (or whatever) without going through the full set of 
initialization routines that your application may have. If no 
files have been selected then your application should open a 
new untitled document and continue from there. The syntax 
is: message%=  FINDERINFO  (count?o, var$[(n)], 
type%[(n)], volume%[(n)]). The message variable is the 
result of the FINDERINFO function. If the result is equal 
to zero then the file should be loaded otherwise the file should 
be printed. The Count% variable returns the number of files . 
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The variable var$(n) is a string variable or string array with 
the names of the files which have been selected. The file type 
of the selected files is stored in a long integer word which 
must be converted to a string by using the MKIS$ statement. 
The volume% variable is the the disk volume where the file is 
located. 

To get the FINDERINFO function to work, first you 
must compile your program as an application. There are two 
or three statements that must be used properly in order to 
compile the program so that the function will work. First 
type CREATOR "ffff" where "ffff" is the creator name 
which will be given to the application. The other statement 
that must match this one is the DEFOPEN "ffffcccc" 
statement which sets up the file type ("ffff") and the file 
creator ("cccc") for the data files created by your application. 
In the demo program the creator is "DAVE" and the file type 
is "DATA". The DEFOPEN statement is used in the 
application program when opening up new data files. Now 
that the creator is the same for the application as for the data, 
we need to set the bundle bit with the BUNDLE 1 
statement. Type BUNDLE 1 in the command window. 
Now it is time to compile the program into an application. 
Select RUN* from the menus to create the application. New 
data files which are created with the application will now be 
linked to each other. Selecting one or more data files while in 
the Finder and selecting PRINT or OPEN will open the 
application which the data files belong and send info to the 
application via the FINDERINFO statement. To see the 
results of this function, you may want to run the demo and 
create a few sample data files and see what happens when they 
are selected for printing or to be opened. 

If you have problems getting the FINDERINFO 
information, be sure that you set the creator and bundle bit 
before compiling the application. You should also be sure to 
define all the variables in the function before calling it. More 
information on the Segment Loader is available in Vol 2, 
Chap. 2 of Inside Macintosh (The Segment Loader chapter). 


WINDOW OFF 

REM Segment Loader Example ZBasic 3.02 
REM €MacTutor 1986 

REM by Dave Kelly 

DIM 31 Name$(5),Vo1%(5), Type&(C52,Mes$C 1) 
REM up to 5 files can be selected. 


DEFSTR LONG 

Count%=2 

Message%=F INDERINFOCCount%, Name$(@), Type&CO), 
Vo1%(8)) 

X&-MEMC- 1) 


WINDOW 1, "Segment Sample", (50, 100)-(475, 300), 257 
IF Count THEN GOSUB "Disp layF INDERINFO" 


MENU 1,9,1,"File" 

MENU 1,1,1,"Create Data File" 

MENU 1,2,1, "Quit" 

MENU 2,0, 1, "Segnents" 

MENU 2,1, 1, "Main Segment" 

MENU 2,2,1," ist Segment" 

MENU 2,3, 1, "2nd Segment” 

MENU 2,4, 1, "3rd Segment” 

MENU 2,5, 1, "Check memory available and unload unused 
segments” 

ON MENU GOSUB "Menuevent" 
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"Loop": 

GOTO "Loop" 
“Menuevent": 
Menunumber=MENUC@) 
Menui tem=MENUC 1) 
MENU 


MENU OFF 
ON Menunumber GOSUB "Filemenu", “Segmenu” 
MENU ON 


RETURN 

"Filemenu": 

IF Menuitem=1 THEN "Openf ile" 
IF Menuitem<>2 THEN RETURN 
MENU RESET 


END 

"Openf ile": 

DEF OPEN "DATADAVE" 

Filenane$-FILESÉK2, "Create new file as ..." ,"Segnent 


DATA") 

IF Filename$="" THEN RETURN 

OPEN 0, 1,Filename$ 

PRINT "New file named ";Filename$;" has been created. ":PRINT 

PRINT "Quit the program and click on "; Filename$; " to see 
how the" 

PRINT "FINDERINFO function works. Select PRINT or OPEN 
from the Finder." 

PRINT "The FINDERINFO function will indicate what has been 
selected." 

PRINT "You may want to create multiple data f iles and try 
printing" 

PRINT "or opening them to see what happens." 

RETURN 

"Segmenu" : 

ON Menuitem GOSUB "Main", "Segi", "Seg2", "Seg3", 
"Memory" 


RETURN 


"Main": 
PRINT "This is part of the main segment" 
RETURN 


SEGMENT 

"Seg 1" 

PRINT “This is part of the Ist segment" 
SEGMENT RETURN 

SEGMENT 

"Seg2" 

PRINT "This is part of the 2nd segnent" 
SEGMENT RETURN 

SEGMENT 

"Seg3" 

PRINT "This is part of the 3rd segment" 
SEGMENT RETURN 

SEGMENT 

"Memory" 

X&-MEKC- 1) 

PRINT "Memory = ";X& 

SEGMENT RETURN 

SEGMENT 

"DisplagFINDERINFO" : 

CLS 


Mes$C0)-"Data file(s) should be loaded" 
Mes$C1)-"Data file(s) should be printed" 


PRINT "Message$ = ";Message$;" Therefore... "; Mes$( 
Message% ) 
PRINT "Count = ";Count&%: "file(s) have been passed to 


this application" 
PRINT "Filenames are:" 
PRINT"Name", "Type", "Vol" 
FOR C=8 TO Count£-1 
PRINT Name$(C), MKI$( Type&(C)), Vo13CC) 
NEXT C 


SEGMENT RETURN 
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Basic School 
Introduction to Print Dialogs 


Exploring the Printing Manager 

This month we'll explore the Macintosh Printing 
Manager. The Printing Manager is a set of RAM-based 
routines that allow you to use standard Quickdraw routines to 
print text or graphics on a printer. Take a look at Inside 
Macintosh for details on the Printing Manager (starting on 
page II-147). Then when you're thoroughly confused, come 
back here and I'll try to clarify some points by example. 

The examples that I've prepared here are written in 
ZBasic and Lightspeed Pascal. The pascal example is included 
to help clarify how the Printing Manager is actually used. 
ZBasic routines call parts of the Printing Manager to enable 
you to have some control over your graphics or text output. 
However, ZBasic does not give you full support even though 
it does support the Printing Manager in more specific ways 
than does MS Basic as of this writing. ZBasic Toolbox calls 
DO NOT support the Printing Manager routines (1.e., they are 
not available). Also, we've found that the ZBasic example here 
does not work as cleanly as the Pascal example, so we invite 
our readers to compare the two and try some alternative Basic 
approaches to improve its performance. 

In ZBasic there is a short list of commands available to 
us which pertain to the Printing Manager (Found on page D- 
58 thru D-63 in the ZBasic manual). They are: 

DEF LPRINT: this command calls up the job dialog 
box so the user may select the page range, print quality, etc. 

DEF PAGE: this command calls up the page setup 
dialog box. The user selects the paper size and orientation via 
this dialog. 

PRCANCEL: this function returns a true when the user 
has pressed the cancel button in the job dialog box (called with 
DEF LPRINT. 

PRHANDLE: this function returns a pointer to the 
print record created by the Printing Manager. By using PEEK 
WORD (two byte peek) the records may be examined and 
important information can be read (see ZBasic manual page D- 
62). 

ROUTE X: this statement routes the output of all 
printing to a specified device X. ROUTE 0 sends output to 
the screen; ROUTE 128 sends output to the printer driver. 
(Note Route 0 does not seem to effect the Printing Manager). 

CLEAR LPRINT: abruptly closes the printer driver. 
If you haven't printed anything, a single sheet of paper (blank) 
is fed out of the printer. 

The whole idea of the Printing Manager is to have one 
set of printing routines that are independent of the type of 
printer used, to which all printed output can be sent. The 
Printing Manager will select the selected printer driver (must 
be on the system disk and chosen by the Chooser desk 
accessory) and directs the printing operation. The ROUTE 
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Print to screen 
Print to printer 
Page Setup 

Job Setup 
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614 
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Quit 9e 
aou l 
Last Page 9999 
* of copies 1 

Fig. 1 Our sample shows print record info 
128 statement directs all output to the specified device, after 
which whatever Quickdraw commands are sent will be 
executed. In ZBasic, the PLOT, CIRCLE, BOX, COLOR, 
PEN, PICTURE commands use Quickdraw, and therefore are 
supported for printing. At this point, Quickdraw commands 
sent to the printer are executed the same as if they were sent to 
the screen (which you've probably done before). One thing 
lacking in the ZBasic implementation is control over the 
PrOpenDoc, PrOpenPage, PrClosePage, PrCloseDoc routines 
as discussed in Inside Macintosh.. Instead the CLEAR 
LPRINT command is used to "CLEAR" out all the impending 
printing. I'm not sure exactly which routines the CLEAR 
LPRINT statement actually calls. 

The PRHANDLE command returns a handle to the 
Printing Manager record. It should be noted that until the 
Printing Manager is opened, the record will contain whatever 
random garbage was located in the memory allocated for the 
print record. You must open the print manager by using DEF 
PAGE or DEF LPRINT. Then the PRHANDLE function 
may be used. The document and page is opened when the 
DEF LPRINT statement is executed. The ZBasic manual does 
not give more than an example to indicate the parameters 
which are returned by PEEKing into the print record memory 
locations. The actual parameters are explained in detail in 
Inside Macintosh.. I attempted to duplicate the data referred to 
in the ZBasic manual (pg. D-62) in the Pascal program. I 
found that it was not hard to follow the data, but there were a 
few mistakes in the ZBasic implementation. Both the printer 
port and the printer type parameters did not seem to function 
properly. These parameters are labeled in the demo program. 
It should also be noted that until a document is printed the 
printing record does not contain the correct information 
(appears to be random stuff). After printing, the data appears 
to be mostly correct except for those noted. The pascal 
program gave correct results every time (before and after 
printing). I have no explanation for why ZBasic does not 
behave like Pascal except that this may indicate another area 
that needs debugging for Zedcor so beware. 

The ZBasic demo demonstrates a technique in using the 


O The Complete MacTutor, Vol. 2 


printing manager from your Zbasic application. The program 
opens the printing manager using the DEF LPRINT statement 
and then prints the print record parameters (as outlined in the 
ZBasic manual), after which a Quickdraw command is given to 
draw a box around the page. The page size was determined 
from the print parameters. A helpful command to use was the 
COORDINATE command. Notice that the coordinates of the 
page were used as the coordinates for the quickdraw drawing 
rectangle (the Grafport) by using the following statement: 
COORDINATE PEEK WORD (P+28),PEEK 
WORD(P+26) which reads the page size from the printing 
record. If your printed output will use fonts, etc., you may 
want to know the page size so you know where to place the 
characters on the page. 

Lightspeed Pascal shows you how the Printing Manager 
is really used. It should be helpful to walk through the setup 
of the Pascal procedures in order to understand the Printing 
Manager better. First off for those just beginning or not 
familiar with Lightspeed Pascal, you must create a new project 
and add the PrLink and MacPrint routines from the Resource 
folder on the Lightspeed Pascal system disk. These are the 
routines which will be loaded into RAM when the Printing 
Manager is opened. Of course, the other Macintosh Toolbox 
calls are automatically included in the new project. Next, the 
file containing the Pascal program below must be added to the 
project. For those using another Pascal or language, note that 
PrLink is Apple's Print Manager interface that is released only 
in object file format. However, Paul Snively published a 
PrLink source file in assembly in a past issue of MacTutor if 
you are interested. The MacPrint file is the interface from LS 
Pascal to the Print Manager and an equivalent set of glue code 
should be supplied by any compiler maker. 

The Print Manager 

Assuming we already have a ready made event loop set up 
that we can use, we will continue by setting up our pascal 
procedures. The first one we'll call from our print routine will 
be 'openprintmgr. This routine uses PrOpen to open the 
printing manager and get a handle pointing to the print record. 
As called for in Inside Macintosh , the print record is created 
with the statement:  prRecHdl := THPrint(NewHandle( 
SIZEOF(TPrint)));. This statement gets a NewHandle to the 
print record 'TPrint'. The record is outlined on page II-149 of 
IM. Keep in mind that the toolbox procedures and functions 
are provided in the MacPasLib and MacTraps libraries files, 
therefore it is not necessary to type in the predefined records 
and other such information (I didn't realize this the first time I 
wrote a program with Lightspeed Pascal) The predefined 
procedures and functions are listed in the appendix of the 
Lightspeed Pascal manual. These functions and procedures 
match those listed in JM. 

Ordinarily when you are preparing to print something 
when you run an application, you will want to be sure that the 
PageSetup is correct (you especially want to do this after 
changing drivers with the Chooser DA). In the procedure 
DoCommand for the case of the menu selection of PageSetup, 
the statement valid := PrStiDialog(prRecHdl); is used to select 
the Page Setup dialog (also called the style dialog). This 
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pascal function returns a boolean reply for the buttons the user 

may have selected (true for 'OK' and false for 'Cancel'). The 

Jobsetup menu case uses the statement valid := 

PrJobDialog(prRecHal); to call the Job dialog. The boolean is 

returned once again indicating what button the user selected. 
So we see that setup of the printing is done as easily in 

Pascal as in Basic! However, printing is quite different in 

Pascal than in Basic. In the example, the print item of the 

menu first selects the PrJobDialog function to get the Job 

information from the user. Next the output must be specified. 

As we discussed earlier, all ZBasic printing is routed to the 

device selected by the ROUTE statement. In Pascal the 

printing grafport is opened with the PrOpenDoc function. In 

Quickdraw all output is sent to the current Grafport. In the 

program the statement myPrPort := PrOpenDoc( prRecHdl, 

NIL, NIL); opens the printing grafport to be used. Next, if 

there is no error, the program calls the PrOpenPage procedure 

PrOpenPage(myPrPort, NIL); to open a printing page. The 

next set of statements or procedures call Quickdraw statements 

and are drawn to the page that has been opened. When each 
page is finished (the example has only one page to print) the 

PrClosePage(myPrPort); statement should be called and 

PrOpenPage to open each new page. Next, you need to check 

to see if spooling was done. If spooling was done, then your 

pages were saved to the disk or memory to be spooled to the 
printer later. To spool to the printer, the PrPicFile procedure 
should be called. If draft printing was selected, then the pages 
are printed immediately (no spooling). You should test to see 
whether spooling was done, and if so, print the spooled 
document. You may want to free some memory so that there 
will be more memory for printing the spooled document. 

Details and another Pascal example are given on pages II-154 

and II-155 of the Printing Manager section of IM.. 

Some hints that you should keep in mind when using 

Quickdraw for printing: 

e Reset font and other grafport information with each new 
page. The grafport is completely reinitialized with each 
new page!. 

e Don't use calls that don't do anything on the printer such 
as erasing, clipping etc. (See comments below on 
LaserWriter restrictions.) 

e Don't use clipping to select the text to be printed. The 
page size may not match your screen size exactly. 

e Don't use non-proportional spaced fonts to align columns 
of text. 

For printing to the LaserWriter (according to IM ): 

e — Regions are not supported. 

e Clipping should be limited to rectangles 

* "Invert" routines are not supported. 

* Copy is the only transfer mode supported for all objects 
except text and bit images. BIC is supported for Text. 
XOR is the only mode not supported for bit images. 

e Don't change the grafPort's local coordinate system (with 
SetOrigin ^ within the printing loop (between 
PrOpenPage and PrClosePage). 

Print Record Information 
Access to the printing record information may be 
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retrieved by using the commands in the getprintinfo procedure 
of the example program. The details here are very clear if you 
refer to the example program and JM. IM details information 
about saving your own print records for use by the printing 
manager instead of the default parameters. 

Termination of the printing manager is done by calling 
the PrClose procedure. There is no need to close the driver 
after each print procedure unless you have a need to free up 
memory. Other low-level driver access information may be 
found in Inside Macintosh also. 

I hope that the examples will help those of you that are 
trying to print graphics with your programs. 

Basic Update 

Here it is a few months after the release of several new 
Basic products and there have not been too many significant 
improvements to any of the Basics except for ZBasic. The 
latest Beta copy of now released version 3.02 appears to be 
a big improvement over the earlier versions. A few changes: 
menus have been redesigned and the program looks and feels 
much more "Mac-like". A bug (something to do with the 
window I/O) was located which had been causing a large 
number of the bombs. It looks like version 3.02 will be one 
we can trust!! The latest word is that Zedcor is now writing a 
new Editor (similar to the MSBasic editor) to replace the very 
poor editor in the previous copies. I hope to be able to 
comment about it some more next month if it has been 
completed by then. ^ Appletalk commands are not yet 
implemented and will bomb if you try to use them. Bugs 
were fixed involving Edit fields, Box fill, POWERS 
statements. The startup screen has been replaced by a simple 
startup dialog box that appears with Andy Gariepy's picture. 
A SHUTDOWN command and auto repeat scroll bars have 
been added. DIALOG(16) may be used to read keypresses 
during event loops. (This replaces INKEY$ during event 
trapping). Looks like its coming right along! A 33-page 
addendum to the ZBasic manual outlines the additions, changes 
and enhancements in version 3.02. For those of you that have 
earlier versions of ZBasic, you will be much more satisfied 
with the improvements. You may want to contact Zedcor 
about upgrade information. 

Rumors are still in the air about the MS Basic compiler 
and improvements to MS Basic. Word is that Absoft has 
completed the compiler and Microsoft has purchased the rights 
to the CLR toolbox libraries and will be bundling the CLR 
libraries with the Absoft MS Basic compiler. More to come 
when I have more to tell. 

REM ZBasic PrintDemo 

REM By Deve Kelly 

REM ©1986 by MacTutor 

WINDOM OFF 

WINDOW ®1,"ZBasic printing", (50,50)-(450,300),3 
W1-WINDOWC22- 1: W2=WINDOWCS )- 1 

DEFDBL INT P:DEF TAB 32 


ON DIALOG GOSUB "Dialogselection" 

DIALOG ON 

ON MENU GOSUB "Menuselection" 

MENU ON 

"Loop" : 

GOTO "Loop" 

"Dialogselection": 
THEEVENT-DIALOG(0 ) 

IF THEEVENT<>5 THEN RETURN 
RETURN 
"Menuse lection": 
MENUNUMBER-MENUC? ) 

MENU I TEM=MENUC 1) 

MENU OFF: MENU :DIALOG OFF 
5s ON MENUITEM GOSUB "Printscr", "Printptr", "Page", 
u fe] u^ 

"dummy", "Clrscr", "Quit" 

MENU ON:DIALOG OFF 


CLS: RETURN 
"Printscr": 
COORDINATE WINDOM 
ROUTE 0 
PICTURE ON 
GOSUB "Your print routine" 


PRINTeCX, 19) “Parameters printed to screen may be in 


error." 
BOX 9,8 TO Wi,w2 
PICTURE OFF, Pic& 
PICTURE,P ic& 
WINDOW PICTURE 5 1,Pic& 


RETURN 
"Printptr": 

DEF LPRINT:CLS 

IF PRCANCEL«»9 THEN RETURN 

P=PEEK LONGCPRHANDLE) 

COORDINATE PEEK WORD(P+28),PEEK WORD(P+26) 

ROUTE 128 

GOSUB "Your print routine" 

BOX 2,0 TO PEEK WORD (P+28)-1,PEEK WORDCP+26)-1 

CLEAR LPRINT 


"Your print routine”: 
PRINT@CX,5) "Print Manager version",PEEK WORDCP) 
PRINT@CX,6) "Driver Info (What's that?)", PEEK 

WORDCP*2) 


PRINTe(X,7) "Vertical resolution",PEEK WORDCP+4) 
PRINTe(X,8) "Horizontal resolution",PEEK WORDCP+6) 
PRINTeCX,9) "Page Rectangle", PEEK WORDCP*8)5;PEEK 


WORDCP* 10); PEEK WORDCP* 125; PEEK WORDC(P+ 14) 


PRINTeCX, 19) “Paper Rectangle",PEEK WORDC(P+ 16); PEEK 


WORDCP+ 18); PEEK WORD(P+20);PEEK WORD(P+22) 


PRINTeCX, 11) "Paper height, width", PEEK WORDCP+26); 


MENU 1,0, 1, "File" : ","; PEEK WORD (P428) 

MENU 1,1,0, "Print to screen" PRINT@(X, 12) "Printer port CERROR!)",PEEK WORD(P+30) 
MENU 1,2,1,"Print to printer PRINT@(X, 13) "Printer type CERROR!)",PEEK WORD (P+32) 
MENU 1,3, 1, "Page Setup PRINTe(X, 14) "First page",PEEK WORD(P*62) 

MENU 1,4,1, "Job Setup PRINT@(X, 15) "Last page",PEEK WORD(P464) 

MENU 1,5,0,'- ; PRINT@(X, 16) "* of copies..",PEEK WORD(P+66) 

MENU 1,6, 1, "Cleer Screen RETURN 

MENU 1,7, 1, "Quit" "Quit": 
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KILL PICTURE Pick 
END 


( Printdemo program by Dave Kelly ) 
( for MacTutor Dec 1986) 

( Lightspeed Pascal 1.0) 

PROGRAM Printdemo; 

USES 


MacPr int; 
T 


appleID = 1; 
fileID = 2; 
eppleMenu = 1 
f ileMenu = 2; 
menuCount = 2; 
printscr = 1 
= 2 

4 


4 


4 


; 
3; 


) 


printptr 

pagesetup = 

Jobsetup = 

clrscr = 6; 

quit = 7; 

plainDBox = 2; 
VAR 

myMenus : ARRAY[1..menuCount] OF MenuHandle; 

theChar : CHAR; 

extended : BOOLEAN; 

doneF lag : BOOLEAN; 

myEvent : EventRecord; 

wRecord : WindowRecord; 

Windowport : Windowptr; 

whichWindow : — Windowptr; 

UpdateWindow : Windowptr; 

windowsize : longint; 

height, width : integer; 

SizeRect, size, dragRect : Rect; 

valid, screenprinted : boolean; 


prRecHdl : THPr int; 
printmgr : boolean; 
myPrPort : TPPrPort; 
myStRec : TPrStatus; 
P : ARRAY 1..15] OF longint; 
pheight : longint; 
pwidth : longint; 
Ptype : integer; 
PROCEDURE SetUpMenus; 
VAR 


i : INTEGER; 
GIN 


myMenus[eppleMenu] := NewMenuCAppleID, chrCappleMark)); 

AddResMenu(myMenus [app leMenu], ‘DRVR' 5; 

myMenus[fileMenu] := NewMenu(fileID, ‘File E 

eppendmenu(myMenus(f ileMenul, ‘(Print to screen;Print to 
printer;Page Setup;Job Setup; (-;Clear Screen;Quit/Q'); 

FOR i := 1 TO menuCount DO 

InsertMenuCmyMenus(il, Ø); 
DrawMenuBar ; 


END; 
PROCEDURE openprintmgr; 
BEGIN 
PrOpen; 
prRecHdl := THPrint(NewHandle(SIZEOF(TPrint))); 
printmgr := true; 
EnableItem(myMenus[f ileMenul, printscr); 


END; 

PROCEDURE getprintinfo; 

BEGIN 
P[1] := prRecHd1**.iPrVersion; ( Print Manager version) 
P[2] := prRecHdl^^.prInfo.iVRes; ( Vertical resolution) 
P[3) := prRecHdl^^.prInfo.iHRes; ( Horiz resolution) 
P[4] := prRecHd1^^.prInfo.rPage.top; ( Page Rec) 
PIS] := prRecHd1^^.prinfo.rPage.left; 
P[61] := prRecHdT^^.prInfo.rPage.bottom; 
P[7] := prRecHd1^^.prInfo.rPage.right; 
P[B] := prRecHdl^^.rPeper.top; ( Paper Rectangle) 


P[9] := prRecHd1^^.rPeper . left; 
P[10] := prRecHd1^^ .rPaper .bottom; 
P[11) := prRecHd1** .rPeper .right; 
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pheight := (C(P[10] - P[8]) * 120 DIV P[212; ( Paper height) 
pwidth := CCPL11] - P[9]) * 120 DIV PI315;( Paper width) 


Ptype := CprRecHd1**.prStl.wDev); (printer type) 
Ptype := (BitAnd(Ptype, 65280) DIV 256); 
PL12] := prRecHdl^^.prJob.iFstPage; ( First page) 
PL13] := prRecHdl^^.prJob.iLstPege; ( Last page) 
PL14] := prRecHdl^^.prJob.iCopies; ( # of copies) 
END; 
printinfo; 
BEGIN 
Getprintinfo; 
textfont(monaco); 
textsize(9); 


moveto(20, 20); 

WriteDrawC'Print Manager Version’); 
moveto( 158, 20); 

WriteDraw(P[1]); 
moveto(29, 38); 

WriteDraw( ‘Vertical resolution'); 
moveto( 158, 30); 

WriteDrawCP(21); 
moveto(20, 40); 

Wr iteDrawC'Horizontal resolution'); 
movetoC150, 40); 

WriteDraw(P[3)); 
moveto(20, 59); 

WriteDraw( ‘Page Rectangle'); 
moveto( 158, 50); 

WriteDraw(P([4], PI51, PI61, P{71); 
moveto(20, 60); 

Wri teDraw( ‘Papar Rectangle’); 
moveto( 150, 60); 

WriteDrawCP[8], P[91, P10], P[11)); 
moveto(20, 70); 

WriteDrawC'Paper height'); 
movetoC150, 70); 

WriteDraw(pheight); 
movetoC20, 80); 

WriteDraw( ‘Paper width’); 
moveto( 158, 80); 

Wr iteDrawCpwidth); 
moveto(28, 99); 

WriteDrewC'Printer type’); 
movetoC150, 99); 

Wr iteDrawCPtype); 
moveto(20, 100); 

WriteDrawC'First Page'); 
movetoC150, 100); 

WriteDrewCP[ 121); 
moveto(28, 110); 

WriteDrewC'Last Page'); 
movetoC159, 110); 

Wr iteDrewCP[ 131); 
moveto(28, 120); 

WriteDrewC'? of copies'); 
movetoC150, 120); 

Wr iteDraewCPL 141); 

END: 
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PROCEDURE DrawingProc; 

BEGIN 
fremerect(myPrPort^ .gPort.portRect); 
printinfo; 


PROCEDURE DoCommand (mResult : LONGINT); 
VAR 


theItem : INTEGER; 
theMenu : INTEGER; 


name : Str255; 
temp, i : INTEGER; 
BEGIN 
theItem := LoWord(mResult); 
theMenu := HiWord(mResult); 
CASE theMenu OF 
eppleID : 
BEGIN 


GetItem(myMenus[appleMenul, theItem, name); 
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temp ;= OpenDeskAcc(name); 
SetPor tCWindowpor t); 


END; 
fileID : 
CASE theItem OF 
IF printmgr THEN 

BEGIN 
SetPortCWindowpor t); 
eraserect(Windowport*.portrect); 
FrameRect(Windowport*.portrect); 
printinfo; 


VOI LORG ICE INCORDOF DOCE 
E = true; 


END; a printscr) 


printptr 
BEGIN 
IF NOT printmgr THEN 
openpr intmgr ; 
valid := PrJobDialog(prRecHd1); 
IF valid THEN 
BEGIN 
myPrPort := PrOpenDoc(prRecHdl, NIL, NIL); 


IF PrError = noErr THEN 
BEGIN 
PrOpenPage(myPrPort, NIL); 
IF PrError = noErr THEN 
DrawingProc; 
PrClosePage(mgPrPort); 


4 
PrCloseDoc(myPrPor t ); 
IF (prRecHd1^^.prJob.bjDocLoop = bSpoolLoop) 
AND CPrError = noErr) THEN 
PrPicFileCprRecHd], NIL, NIL, NIL, myStRec); 


8 
BO; 
Jobsetup : 
BEGIN 
IF NOT printngr THEN 
openpr intmgr; 
valid := PrJobDialog(prRecHd1); 
END; 
pagesetup : 
BEGIN 
IF NOT printmgr THEN 
Openpr intmgr; 
valid := PrStiDialogCprRecHdl); 
8 
clrscr : 
BEGI 
eraserect(Windowport* .portrect); 
screenprinted := false; 


IF printmgr THEN 
BEGIN 


PrClose; 
printmgr := false; 


doneFlag := TRUE; 
END; 
OTHERWI SE; 
ir. (i tenCase) 
END; ( nenuCase ) 


SetPor tCWindowport); 
HiliteMenuC0); 


END; 

(Here is the Main Program) 
BEGIN 

Init6ref CéthePort?; 
InitFonts; 
FlushEventsCeveryEvent, 2); 
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eai 

InitMen 

InitDielogsCNIL); 

InitCursor; 

SetRect(sizeRect, 50, 50, 450, 300); 
dragRect := sizeRect; 

doneFlag := FALSE; 

printmgr := false; 

screenprinted := false; 


Windowport := Newwindow(@wRecord, sizeRect, '', true, 
plainDBox, POINTERC- 15, false, Ø); 

SetPort(Windowport?); 

SetUpMenus; 

( This is the main event loop) 

REPEAT 

SystemTask ; 


IF GetNextEventCeveryEvent, myEvent) THEN 
CASE myEvent what OF 
MouseDown : 
CASE FindWindow(myEvent where, whichWindow) OF 
inDesk : 
; (Not used} 
inMenuBar : 
DoCommand(MenuSe lect (myEvent .where)); 
inSysWindow : 
SystemClickCmyEvent, whichWindow); 
inContent : 


BEGIN 
IF whichWindow «> FrontWindow THEN 
Se lectWindowCwhichWindow) 


BEGIN 
Global ToLocal(CmyEvent.where); 
extended := BitAnd(myEvent modifiers, shif tKey) 


END; 
(J 


è 
indreg : 
Wot used) 

inGrow 
(Not used) 
inGoAwey : 
; (Not used) 
END; 


mouseUp : 

; (Not used) 

keydown, autokey : 
BEGIN 


theChar := CHRCBitAnd(myEvent .message, charCodeMask)); 
IF BitAnd(nyEvent.modif iers, cmdKey) © Ø THEN 
DoCommand(MenuKey( theChar 2); 


keyUp : 
; (Not used) 
updateEvt : 
IF screenprinted THEN 
BEGIN 
UpdateWindow := WindowPtr(myEvent . message); 
BeginUpdateCUpdateWindow); 
SetPortCUpdateWindow); 
ereserectCUpdateWindow^ .portrect); 
FreneRectCUpdateWindow^ .portrect); 
printinfo; 
EndUpdateCUpdateWindow); 
8 
diskEvt : 
; (Not used) 
activateEvt : 
; (Not used) 
networkEvt : 
(Not used) 
driverEvt : ; (Not used) 
OTHERWISE; —. 
END; Pod! 
UNTIL doneF18g; m 
END. 
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Threaded Code 
Animated Hanoi Towers in NEON 


Lately, we have had a number of requests for a column on 
NEON. Since no neon articles have been forth coming, I have 
been asked to temporarily switch from my usual Forth 
ramblings to NEON. Since NEON is so close to Forth, we 
have decided to show a NEON example this month for a 
change. In light of this, we will re-name this column 
"Threaded Code" to cover all the Forth like object oriented 
languages that are Forth derivatives on the Mac. 

The principles of object oriented programming have 
already been explained in several earlier columns (see LISP 
V1#6, NEON V1#8), so I am not going to dwell on that here. 
Rather, we are going to look at the famous Towers of Hanoi 
algorithm from an object-oriented point of view, gaining some 
on-hands experience with an example that - I feel - is 
particularly appropriate for this approach. 

Let's recall: The ‘towers’ are three stacks of disks (Fig. 1). 
The leftmost one is filled with n disks stacked on top of one 
another in order of decreasing size, the other two are initially 
empty. The objective is to move the disks from the leftmost 
to the rightmost position, one by one, in such a way that a 
larger disk is never put on top of a smaller one. This works if 
one uses the middle position as a 'scratchpad' (try it out with 
pieces of paper), even though this is a rather tiresome 
procedure, if performed manually. 

Fig. 1: Initial and final positions of Towers of Hanoi. 


LL 
Ld 


This is, of course, where Mac comes in; and the 
algorithm to solve the puzzle is very short if written 
recursively. In pseudo-Pascal it would look like this (see also 
John Bogan's Modula-2 column in V 146): 


procedure hanoi (n, start, inter, finish: integer); 
beg! 


n 
if nog then 
begin 
hanoi (n-1, start, finish, inter); 
move (n, start, finish); 
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hanoi (n-1, inter, start, finish) 
end 


end; 


where n is the number of disks, and start, inter and finish 
denote the starting, scratch and final positions for the disks. 
move is a procedure that (somehow) moves the disk from one 
stack to another. 

OK, so if we set up a stack of disks, provide three towers 
to put them on to, and execute this procedure, we should be 
able to watch how Macintosh solves the Towers problem. 

There are two things to notice: First, the definition is 
obviously recursive, second, we have to be careful how to 
represent our data. 

Recursive definitions - NEON and MacForth 

A very simple recursive procedure is the definition of 
the factorial of an integer number, which is given at the very 
beginning of the program example (listing 1). This definition 
works in NEON; you may refer to a word within the definition 
of the word itself (By the way, even if you weren't allowed to 
do it that way, you could resort to the forward declaration). 

MacForth, however, sets the smudge bit in the 
vocabulary while compiling a new definition; therefore the 
word being defined is not known to the system at compile 
time and cannot be referred to by itself. You have probably 
seen the effect of the smudge bit already; when the compiler 
exits a declaration due to an error, words will show the first 
letter of the latest definition changed (in fact, it has the 8th bit 
set). One can easily circumvent this restriction by writing 


: factorial [ smudge ] 
dup if dup 1- factorial * else drop 1 then ; 
smudge 


ie., executing smudge during the compilation of 
factorial and resetting it afterwards. This will give a working 
definition, within the limit that is given by the 32-bit 
maximum integer size of the Macintosh. 
Representation of disks and towers as 
NEON objects 
Since we are, in fact, simulating material objects, 
moving them around and also displaying the result of our 
simulation on the screen, the Towers of Hanoi problem seems 
to be idealy suited for an object oriented language like NEON. 
We could define 'disks' as objects that can be drawn, put on 
top of other objects, called 'towers' and moved between them. 
The towers will automatically keep track of how many disks 
are on them, the disks will 'know' what tower they are on and 
how to 'draw themselves'. 
The Three Towers 
There is one predefined class in NEON, ordered-col, that 
represents a list of variable size. Elements of that list are 4- 
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byte entities. A tower in our example will be an ordered-col 
of specified maximum size. In addition, it will have a certain 
position on the screen, which can be accessed by the methods 
getX: and getY: and a draw: method that draws the tower at 
its position in the current grafPort. That's all we need as a 
‘stacking device' for the disks. Everything else is taken care of 
by the disks themselves, as you will see soon. 

The instance variables needed for every object of class 
tower are: rects that correspond to the base and the post, and 
ints that contain the x and y position of the center of the 
base. 

Now we could start our simulation by creating three 
tower objects, e.g. 


tower babylon 
tower london 
tower pisa 


Except for the fact that this looks cute, there is really no 
advantage in having named objects here. Just to make the 
point, and as an example how objects can be made to refer to 
other objects, we set up the three towers as a 3-element 4-byte 
array towers. This gives the additional advantage that we can 
refer to them by index. The array is initialized by the word 
make.towers, which shows how one can create ‘nameless' 
objects on the heap with the heap» prefix (in my review 
copy of NEON, this information is hidden somewhere in the 
pages of Part III Chapter 1; I am confident that a revised 
manual will have this in the glossary). 

xcenter ycenter ndisks heap» tower will leave 
on the stack the address of a new object of class tower created 
on the heap. The tower contains ndisks disks, and its base is 
centered at (xcenter,ycenter). 

ndisks make.towers creates three of these gizmos 
equally spaced near the bottom of the screen, each of them 
having space for disks, but no disks on them yet. Their 
addresses are put into the array towers. 

draw.towers will draw the towers, but not the disks. In 
this definition you see how one makes use of late binding; we 
want to send a draw: message to an object which is exactly 
known only at execution time (since towers could contain 
any kind of address). Therefore, if we want to draw the i-th 
tower, we have to write draw: [ i at: towers ] . (The 
same is true in immediate execution mode: draw: addr will 
abort with an error message, while draw: [ addr ] will do 
the correct thing, if addr is the address of a 'drawable' object. ) 

After you're finished with the example, you might want 
to dispose of them by calling dispose.towers. The same 
should be done to the disks; try writing a definition that will 
do the job. 

Moving around the disks 

The disk objects are more complicated than the towers. 
They have to be initialized and drawn; they will come in 
different sizes; and they will move around, sitting on one of 
the three stacks at any given time. 

Since the disks won't shrink or grow, their size is known 
at initialization time and will be passed as a parameter to 
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classinit:. This method also needs to know which tower the 
disk is on at the beginning (we pass the address of the tower 
object and put it into the instance variable which). The newly 
created disk it then put on top of the tower which it is 
associated with. 

The draw: method is not quite general for disks, but very 
specialized for Hanoi disks: it makes use of the fact that a disk 
is only drawn right after it has been put on top of a stack. 
Since the size of that stack is known (by executing size: [ 
get: which ] ), the position of the topmost disk is exactly 
determined. Therefore, draw: calculates first the coordinates of 
the center of the disk and saves them in instance variables for 
later use, then does the necessary Quickdraw calls. If one 
wanted to do other things with the disks, e.g. drawing them at 
different places, one might want to factor out the code that 
calculates the coordinates. 

undraw: removes the disk from its position (but not 
from the list which is being kept in the tower), and redraws 
the little black rectangle, the part of the post that had been 
overwritten previously. Here again, you see that a special 
assumption about the behavior of the disk is made: namely, 
that it does not cover anything but a certain part of the tower 
post. 

dest move: finally will move a disk from wherever it 
was to the tower dest, undrawing and redrawing as necessary. 

Object interdependence 

You see the line that we draw between general and 
specialized behavior of objects. The fact that a disk is 
displayed as a pattern-filled rectangle that takes up a certain 
amount of space on the screen is a behavior that would be 
general to any 'disk-like' object (unless we choose to rotate it 
as well). Association to another object, the tower, would also 
be something that could be implemented into an idealized 
general' disk. But the fact that this other object has a certain 
shape and that the disk can only be put onto it in a certain 
manner is extra information which the disk 'knows' about and 
which is used within the code that defines some of its 
methods. 

To make the objects even more independent, 'MacDraw- 
like, would require a much more sophisticated interface 
between towers and disks than given here. One would then 
rather start by defining a subclass of window which has e.g. 
an ordered-col of objects associated to it, and which would be 
updated each time one of the objects is moved. I felt this 
would have created too much overhead to the program 
example. But you can see that MacDraw is not very far away, 
just go ahead and create that window, a set of objects and their 
appropriate behavior, and there you go... send us the code 
when you're done, we'll publish it. 

Main routine 

The main routine simply creates a Hanoi puzzle of 
ndisks disks and draws the initial position. ndisks i j k 
hanoi will move those disks ( or less, if you set ndisks 
differently) according to the rules of the game from tower i via 
j to k. Try 

10 main 

10 0 1 2 hanoi 
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or, to create a ‘forbidden’ pattern 

10 main 

5 0 1 2 hanoi 

5 0 2 1 hanoi 

5 1 0 2 hanoi 

Have fun! Determined FORTH programmers might try to 
rewrite this example into MacForth or some other Forth. The 
Hanoi routine itself is simple. Doing the data representation in 
the same way should look rather more complicated... 

Change of address 

We have moved in the meantime. Please address all 
questions, remarks, suggestions, etc. regarding this column to: 

Jórg Langowski 

EMBL, c/o I.L.L., 156X 

F-38042 Grenoble Cedex 

France 


Listing 1: Towers of Hanoi code 
( € 110285 MacTutor by JL ) 


: factorial dup if dup 1- factorial * else drop 1 then 


‘class tower «super ordered-col 
rect base 
rect column 
int xcenter 
int gcenter 


:M classinit: ( xcenter ycenter -- ) 
put: ycenter put: xcenter 
get: xcenter 78 - get: ycenter 16 - 
get: xcenter 78 + get: ycenter put: base 
get: xcenter 4 - get: ycenter 
limit: self 10 * 50+ - 
get: xcenter 4 + get: ycenter 16 - 
put: column 
:M drew: Ø syspat dup fill: base fill: column ;M 
:M getX: get: xcenter ;M 
:M getY: get: ycenter ;M 
,class 
‘class disk «super object 
int size 
ver which 


rect image 
int xc int yc 
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loop 


:M classinit: ( which size -- ) 
put: size put: which 
addr: self add: [ get: which ] ;M 


:M drew: 
getX: [ get: which ] put: xc 
getY: [ get: which ) 
12 - size: [ get: which ] 18 * - put: yc 
get: xc get: size - get: yc 4- 
get: xc get: size * get: yc 4* put: image 
3 syspat fill: image draw: image 
„M 
4 


:M undraw: 19 syspat fill: image 
get: xc 4- get: yc 4- 
get: xc 4+ get: yc 4+ put: image 
Ø syspat fill: image 


4 


:M move: ( dest -- ) 
undraw: self 
addr: self add: [ dest ] 
size: [ get: which ] 1- 
remove: [ get: which ] 
dest put: which drew: self 
jM 


;cless 
3 array towers 


: make.towers ( ndisks -- } 
3 8 do 
i 150 * 100 + 280 ndisks heap? tower 
i to: towers loop ; 


: drew.towers 
3 Ø do drew: [ i at: towers ] loop ; 


: dispose.towers 3 Ø do i dispose: towers loop ; 


: hanoi ( n start inter finish -- ) 
nif n 1- start finish inter hanoi 
finish at: towers 
move: [ last: [ start at: towers ] ] 
n 1- inter start finish hanoi 
then 


: main ( ndisks -- ) 
ndisks make.towers cls draw.towers 
ndisks 8 do 
Ø at: towers 6 ndisks i - 4* + heap? disk drop 
drew: [ last: [ Ø at: towers ] ) 


aaa «oN 
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Threaded Code: Neon 


A Generic Application 


The Edit window 

The Hanoi towers were fun to play with. Today, we'll 
Start doing something '‘serious' and develop a template 
application in NEON, which will eventually develop into the 
skeleton of a terminal program. In this issue, we'll first set up 
the object definitions and the appropriate methods that are 
necessary to handle TextEdit records. 

'Application templates' in NEON 

The word 'application template' has a somewhat different 
meaning under NEON than, let's 
Say, in assembly language or C, 
since NEON provides you with a 
lot of the event handling support 
that has to be taken care of 
explicitly otherwise. In principle, 
one could setup an application 
shell - e.g. a window that supports 
text editing and has the basic File 
and Edit menus and the appropriate 


anana n stars Tara Tu a P B na, 


eo, MEE RUM 
(change control 
and associated 


event handlers - in NEON from object behavior) 
Scratch. One would start by 

defining windows, controls and 

menus using only  toolbox 

definitions and the basic Object = 


class to build on. But this would 
mean reinventing the wheel and 
not taking advantage of the features 
that are already built into NEON. 


If any of these standard definitions will ever have to be 
changed, one can even do that because their source code is 
part of the NEON system. 

So for the time being we will use the classes that are 
already provided by the NEON system. This way the main 
‘event loop’ becomes very simple; the NEON manual suggests 
to handle almost all the important events by just saying 


begin key key: xywindow again 
with en arbitrary window xywindow, or even 
in 


key key: [ frontwindow ] again 

where frontwindow generates the address of the 
frontmost window object (by calling FrontWindow from the 
toolbox). 

This will be the complete event loop, the reason being 
that key waits for a keystroke, which is the thing that will in 
most cases have to be processed separately by your 
application. While waiting, key automatically tracks all 
mouse events and associated window activate and update 
events. The routines that handle these events are defined 
separately by the actions: method for windows and controls, 
and in the menu definition file for menus. 
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the window one has to write a loop that is cycled often enough 
and does not stop at key waiting for a keystroke.I'll come 
back to this issue after having described the class definitions. 
The editwindow class 

We will first define the main object in our application, 
which is a window that contains a vertical scroll bar and has a 
TE record associated with it. Other than in MacForth, there is 
no predefined space in a window record to hold a pointer of a 
TE record, nor are there predefined routines that will do the 


(select items) 


(mouse 
events) 


send keystroke to 
front window 


Nd (drag, size, activate/deactivate) 


Fig. 1 : Event loop in NEON 


Events other than keystrokes detected by key will be 
sent to the appropriate (window, control, menu) objects, and 
theses objects will take care of handling them as the action 
words have been set up accordingly. [Important note: as far as I 
have found out on my review NEON 1.0 version, even 
Control- keystrokes will not cause key to exit but will be 
sent to the menu bar]. 

Fig. 1 gives an illustration of the action of key. 

This is the structure that most NEON programs should 
make use of since different window and control Objects can be 
defined in a very straightforward way, very independent of one 
another. 

This is also how we are going to proceed to develop a 
simple NEON application: a TextEdit window that can be 
grown and dragged, which will accept text from the keyboard 
and whose text may be copied, cut and pasted through an Edit 
menu. A File menu will have Quit as its only option. 

There is one problem, however, with using key as 
defined in NEON when one calls the TextEdit routines. The 
convention is that you call TEIdle in the main event loop as 
often as possible so that the blinking caret is updated. key 
does not do this, so when manipulating a TextEdit record in 
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editing on such a window. This is good and bad; bad since it 
requires work on the part of the programmer and good because 
we can define the object exactly the way we want it to be and 
know the structure of the methods that we associated with it. 

Refer to Listing 1 for our program example. An 
editwindow is defined as an object of the superclass 
ctlwindow, and you will have to load ctl, ctlwind and 
vscroll into the NEON system before loading this definition. 
Associated with this window are the instance variables text, 
TEscrollbar and position. text is a TErecord object, and 
we'll get to its definition soon. TEscrollbar is a variable that 
holds the address of a vscroll object (for reasons that are 
explained in detail in the NEON manual, a control cannot be 
an instance variable itself). 

position will be used to keep track of the current 
position within the text. The reason why this has to be done 
is that after a call to TEcaltext (recalculate line positions after 
resizing the destRect), the start position of the text put into 
the destination rectangle is reset to the beginning of the text. 
However, the value of the vertical scroll bar will not have 
been reset, and it will show a position somewhere within the 
edited text while what is actually displayed is the very 
beginning. 

So there remain two possibilities: after recalculating the 
text, one can either reset the control to zero or scroll the newly 
aligned text back to the position given by the scroll bar. We 
choose the latter alternative here. 

In our example, the scroll bar will not reflect the relative 
position in the text, but rather the absolute position counted 
in pixels from the beginning (mainly because of my laziness 
to write a separate scaling routine). The scroll bar range will 
be 0 to 2000, and the up/down arrows will change the control 
by 10 on every click, while page up/page down will change it 
by 100. 

When the editwindow object is created, a vertical scroll 
bar is generated on the heap and its address put into the 
instance variable. The text edit record has to be initialized 
separately using the teinit: method. 

Behavior of the Edit Window 

The function of the edit window is very largely 
determined by the draw: method. This method will be called 
automatically whenever an update event for that window 
occurs, e.g. after dragging or resizing. 

In our case, the view and destination rectangles of the TE 
record will always be equal to the content region of the 
window minus the rectangle containing the vertical scroll bar. 
draw: first calculates the new scroll bar and puts it in the 
right position into the window (which might have been 
resized). Then the window itself is drawn by calling the draw: 
method of the superclass. For displaying the text, the new 
view and destination rectangles are then calculated by the 
getcont: method, the text is recalculated and scrolled into the 
position given by the value of the scroll bar. 

Thereafter the window contents are updated by setting the 
whole of the content region invalid and doing a TEupdate 
between calls to BeginUpdate and EndUpdate. 

A redefinition of the draw: method of a window is one 
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way to define its update behavior. The other possibility, also 
given in the NEON manual, is by putting the cfa of a colon 
definition into the draw vector using the actions: method. 
After playing around with this feature for a while and getting 
bombed down quite a few times, I looked into the source code 
of draw: to see what had gone wrong. 

The logic behind NEONSs built-in draw: method is the 
following: First, the window is redrawn doing the appropriate 
updating between calls to BeginUpdate and EndUpdate. The 
last statement in the method definition is exec: draw. This 
jumps to the user-defined action vector, then exits the method. 
The code that you put into your action vector would then 
consist of updating code sandwiched between BeginUpdate and 
EndUpdate. Of course, if you make the mistake to send draw: 
to your window from within this code, you will get an infinite 
recursion which you probably never wanted in the first 
place.... therefore the bomb. 

The updating that we do here manipulates the windows 
own TextEdit record. Since we prefer to hide this from the 
outside world as much as possible, we redefine draw: within 
the window rather than by changing the action vector. 

Editing - the TErecord class 

The actual text editing methods such as cut, copy, paste, 
handling of mouse clicks and scrolling are just passed through 
by the edit window to its own TE record, where they have 
been defined. This leads to the definition of the TErecord 
class. 

A NEON TErecord object constitutes the interface to 
the Toolboxs TextEdit record (whose structure has been 
explained in several different columns in MacTutor, includingh 
this one). Just to refresh your mind, this data structure 
contains a handle to the text to be displayed, which is stored 
separately, and information which is necessary to display the 
text. The TErecord definition provides you with methods to 
access most of the fields in the TextEdit record, change them 
and do editing operations on the text. 

Most of the methods in the TErecord are simple calls of 
the corresponding toolbox routines with the handle of the TE 
record as the top of stack parameter. In some cases, since stack 
items are always 32-bit parameters in NEON, it was necessary 
to use pack and unpack. For instance, NEON gets the 
coordinates of rect objects as separate 32-bit numbers on the 
stack, with the order being ( left top right bottom ). The 
methods in our example that extract the coordinates of the 
view and destination rectangles out of the TextEdit record will 
of course leave them on the stack in this format, so they may 
be passed along to other rect objects. 

A new TextEdit record is assigned to a TErecord object 
by sending a new: message to it, parameters on the stack 
being a zero (to hold the TEnew function result) and pointers 
to the destination and viev rectangles. Note that you will have 
to call this method from outside using absolute addresses for 
the rect objects, just as the NEON manual tells you. 

The handle to the TextEdit record returned by TENew is 
stored in the instance variable TEhandle, the other instance 
variable is chars, which is used as an internal handle to the 
text being edited. 
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Menu definitions 

There will be - in addition to the apple menu - two 
menus in our mini-application, File and TEmenu. Menus 
are set up in NEON in a way very different from MacForth, in 
that the menu text is contained in a separate text file and read 
in during setup of your application. This is very similar to the 
resource file concept but not quite the same. Differences are: 

- the word that is executed upon selection of a menu item 
is given in the menu text file; 

- control key handling is automatic and does not need do 
be taken into account by the application explicitly. All one 
has to do is to specify the control key in the menu definition 
text, and the menu item will be selected when this key is 
pressed. 

One consequence of the inclusion of a menu item's action 
word in the menu text file is that this word has to be known 
to the NEON system when the application is loaded. This 
means that when you install an application in the way the 
NEON manual describes, you cannot use any of the words of 
the NEON kernel as menu action words. After installing the 
NEON kernel, these words cannot be found in the dictionary 
anymore, so the menu could not be loaded. So if you want to 
use e.g. bye as one of the selections in a menu, you would 
have to write a small 'interface' such as 

: ciao bye ; 

in your application. ciao would be known even to an 
installed NEON system, whereas bye would not. 

The texts used for the menus here are given in listing 2. 

Action words for controls and windows 

Control and Window action words are put into the 
respective objects by executing the actions: method. For a 
vertical scroll bar, 5 parameters are expected which are the 
handlers for the up, down, page up, page down and thumb 
regions of the bar, and for the window we need 4 cfas of the 
close, activate, update and content-click handlers. 

These words are defined in the example, and their action 
vectors are initialized by two words initctl and initwind, 
which are called from the application's main body. 

Main event loop 

start.edit is the event loop. We emulate what is done 
by key automatically and write an endless loop in which: 

- TEIdle is called periodically so that the caret is blinking 
normally, 

- the cursor is adjusted to show an I-beam in the content 
area minus scroll bar of the window and the northwest arrow 
otherwise, 

- events are tracked by next: fevent and keys are 
transferred to the editing window. Other events will be taken 
care of automatically by the NEON system. (Only key down 
events return from next: fevent with a true result). 

Starting up the application 

main starts up the application. The NEON window is 
closed, the menus, editing window and controls set up, some 
initial text put into the TErecord and the editing loop started. 
We will continue this example in the next issue to see how 
text is transferred to/from the scrap and how the serial port can 
be interfaced to this editing window. 
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Closing Remark - making a stand-alone 
application (?????) 

I tried to make a stand-alone application from this 
program by applying the strategy that is proposed in the 
NEON manual, executing 

finalsave TE.DEMO main ciao 

and then clicking the TE.DEMO icon from the desktop. 
This did not give successful results, no matter what I tried I 
got a #2 bomb. This seems to happen at the point where 
new: [ obj: TEscrollbar ] is called from the method 
initscroll: in editwindow. This works perfectly when 
NEON is called up in the normal way and the example loaded 
thereafter. Trying to do this in a stand-alone NEON 
application gives the bomb. 

I have not figured out more about this error message, 
except that I sometimes (in a seemingly irreproducible way) 
get the same error message when trying to built the grdemo 
example on the NEON source disk. When this column is in 
print, I will probably have an answer from Kriya systems that 
solves my problems. 

Stay tuned till next time. MacForth purists don't cancel 
your subscriptions yet, you won't be forgotten. 


Listing 1: Text Edit example 


\ application template example for MT V283 
V Cc) J. Langowski 1985 for MacTutor 


:class TErecord «super object 
handle TEhandle 
handle chars 


:M new: call TEnew put: TEhandle ;M 
:M release: 

get: TEhandle call TEDispose release: TEhandle A. 
:M setdest: 


pack ptr: TEhendle 4+ ! pack ptr: TEhandle ! jM 
:M getdest: ptr: TEhandle @ unpack 

ptr: TEhandle 4+ @ unpack ;M 
:M setview: pack ptr: TEhandle 12 + | 

pack ptr: TEhendle 8+ ! ;M 
:M getview: ptr: TEhandle 8+ @ unpack 

ptr: TEhandle 12 + 6 unpack ;M 


:M getheight: ptr: TEhandle 24 + we JM 
:M setheight: ptr: TEhandle 24 + w! ;M 


:M getfont: ptr: TEhandle 74 + wê ;M 
:M setfont: ptr: TEhendle 74 + w! ;M 
:M getface: ptr: TEhandle 76 + wê ;M 
:M setface: ptr: TEhandle 76 + w! ;M 
:M getmode: ptr: TEhandle 78 + wê ;M 
:M setmode: ptr: TEhandle 78 + w! ;M 
:M getsize: ptr: TEhandle 80 + w8 ;M 
:M setsize: ptr: TEhandle 80 + w! ;M 
:M setcr: ptr: TEhandle 72 +w! :M 


: d 

:M recalc: get: TEhandle call TEcaltext ;M 

:M update: getdest: self put: temprect 
abs: temprect get: TEhandle call TEupdate ;M 

:M key: get: TEhandle call TEkey ;M 
TEhandle call TEcut ;M 
TEhandle call TEcopy ;M 
TEhandle call TEpaste ;M 
TEhandle call TEdelete ;M 
TEhandle call TEinsert ;M 


:M cut: get: 
:M copy: get: 
:M paste: get: 
:M delete: get: 
:M insert: get: 


:M idle: get: TEhandle call TEidle ;M 

:M just: get: TEhandle call TEsetjust ;M 
:M click: get: TEhandle call TEclick ;M 

:M act: get: TEhandle call TEactivate ;M 
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:M deact: get: TEhandle call TEdeactivate ;M : inup get: [ getscr: mytext ] 


:M scroll: pack get: TEhandle call TEscroll ;M 19 - put: [ getscr: mytext ) adjust: mytext ; 
:M setbase: ptr: TEhendle 26 + w! ;M : indn get: [ getscr: mytext ) 
:M gettext: Ø get: TEhandle call TEgettext 10 + put: [ getscr: mytext ) adjust: mytext ; 
put: chars ptr: chers ;M : pgup get: [ getscr: mytext ] 
:M settext: swap *base swap get: TEhandle 100 - put: [ getscr: mytext ) adjust: mytext ; 
call TEsettext ;M : pgdn get: [ getscr: mytext ] 
100 + put: [ getscr: mytext ] adjust: mytext ; 

;class : thmb adjust: mytext ; 

: initct] «[ 5 D ‘cfas inup indn pgup pgdn thmb 

: calc.scroll.length (1 trb-—-) 1t bt-; actions: [ getscr: mytext ) ; 

:cless editwindow «super ctlwind : edjust.cursor wordÜ where: themouse pack 
TErecord text getcont: mytext put: temprect abs: temprect 
var TEscrollbar call ptinrect word 
int position if ibeamcurs else call initcursor then ; 

:M teinit: new: text ;M : stert.edit begin idle: mytext adjust.cursor 
:M settext: settext: text ;M next: fevent 
:M terec: addr: text ;M if drop 255 and mekeint key: mytext then 


:M key: key: text ;M again ; 
:M idle: idle: text ;M 

:M act: ect: text ;M : cut cut: mytext ; 
:M deact: deact: text ;M : copy copy: mytext ; 
:M click: click: text ;M : paste paste: mytext ; 
:M cut: cut: text ;M 


:M copy: copy: text 5M : ciao bye ; 

:M paste: paste: text ;M 

:M getcont: getrect: self swap 15 - swap ;M 3 menu TEmenu 

:M drew: getvrect: self calc.scroll. length 1 menu filmen 

16 swap size: [ obj: TEscrollbar ] 
moveto: [ obj: TEscrollbar )] draw: super : main close: fwind " TEmenu.txt" getmtxt 

getcont: self setdest: text edw " Test Edit Window" docwind true true 
getcont: self setview: text recalc: text new: mytext 
Ø get: [ obj: TEscrollbar ] -1 * scroll: text initwind 


getrect: self put: temprect 


call teinit Ø abs: edest abs: eview teinit: mytext 
ebs: temprect call invalrect 


32 32 500 300 true setgrow: mytext 


Cabs) call beginupdate update: text 10 10 500 300 true setdrag: mytext 
(abs) call endupdate ;M Ø setcr: mytext  initscroll: mytext  initct] 
:M release: release: text dispose: TEscrollbar ;M " Text Edit Window, example MacTutor V283 


:M setcr: setcr: text ;M 


(c) 1985 J. Lengowski" settext: mytext 
:M showscr: show: [ obj: TEscrollbar ] ;M : i 


Ø 2008 putrange: [ getscr: mytext ] 


:M classinit: heap? Vscroll put: TEscrollber ;M select: mytext set: mytext start.edit 
:M. initscroll: getvrect: self calc.scroll. length ; 

addr: self new: [ obj: TEscrollber J ;M Listing 2: Menu texts used by the example 
:M scroll: 


dup +: position Ø swap -1 * scroll: text ;M 


l Put these menus into the file "TEmenu. txt". 
:M adjust: get: [ obj: TEscrollbar ] 


get: position - scroll: self ;M APPLEMEN 1 
:M getscr: obj: TEscrollbar ;M "$ 14" 
;cless "About Neon™..." about 
a ee eee ee s nul ] 
rect edw "RES" DRVR \ get desk accy names 
rect edest rect eview "\\\" 
50 50 400 250 put: edw FILMEN 256 
9 5 380 240 put: edest get: edest put: eview "File" 
"Quit" ciao 
editwindow mytext "\\\" 
TEMENU 261 
: myact act: mytext ; "TEMenu" 
: mydeact release: mytext bye ; "Cut/D" cut 
: mycont "Copy/F" copy 
where: fevent g-?1 false makeint click: mytext ; "Peste/G" paste 
: initwind «( 4 ]> 'cfes mydeact myact null mycont "\\\" 
actions: mytext ; XXX 
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Threaded Code: Neon 


Scrap Support for Terminal Emulation 


“NQSD" terminal emulator 


First, lets continue and finish the example from last month's 
NEON column by adding (finally!) the scrap support (You 
may remember that I promised to write something about scrap 
handling some time ago). 


Actually, I have reworked the example somewhat. Neon 
Supports a rudimentary form of multitasking which makes 
event handling a lot simpler, so I added that; then, of course, I 
promised to add support for serial I/O so that we would end up 
with a not-quite-so-dumb terminal program (not quite, since 
we will be able to do cutting/pasting and therefore capture text 
files). The ‘finished’ example (to be expanded and improved by 
you) is shown in Listing 1. 


Scrap handling in NEON 
(and other Forths, for that matter) 


Let's first look at the way the scrap can be passed around 
between applications. I will limit myself to text Scrap only, 
since that's what our example is using. 


The crucial point here is that the ‘scrap’ that TextEdit uses is 
internal to the TextEdit routines, so that it will not 
automatically become part of the clipboard after a TECut is 
executed. If you don't believe this, start up last month's 
example and open the Note Pad desk accessory. Cut or Copy 
some text from the TE window (using the TEmenu), click the 
notepad and then try to paste it (using ctrl-V, since the Edit 
menu has been lost). Nothing happens. Also, if you cut text 
from the notepad and try to paste it into the TEwindow, that 
won't work either. 


This proves what you might have known already, namely that 
the desk scrap (contained in the Clipboard) does not have 
anything to do with the TE scrap, and that we need a set of 
routines that transfer text between those two kinds of scrap. 


Refer to the listing. The magic numbers that we need are 
system globals, the length of the TE scrap at $ABO and its 
handle at $AB4. The length of the desk scrap is maintained in 
$960. 


Two routines transfer the scrap from TE to desk and vice 
versa. put.tescrap, as you might have guessed, takes the TE 
scrap and puts it into the clipboard. It uses the toolbox trap 
putscrap, which is a function that returns a 32-bit result code 
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(0 if ok) and is called with the stack set up as follows: 


- 0 for the return code 

- a 32-bit integer giving the length of 
the data that goes into the scrap 

- the resource type, 'TEXT' or 'PICT' 

- a pointer to the beginning of the data. 


We first check whether there is any text edit scrap available at 
all, and if it is, zero the desk scrap (=: clear the clipboard). 
Then the parameters for putscrap are set up, converting 
absolute addresses to NEON-relative (-base) and dereferencing 
handles where necessary. After exiting, the clipboard will 
contain a copy of the text edit scrap. The resource type 
constant 'TEXT'is contained in txtype, which is defined in 
FrontEnd. 


get.tescrap does the opposite: if desk scrap is available, it will 
transfer it into the TE scrap by calling getscrap with the 
parameters: 


- 0 to hold the return result (the total 
length in bytes) 

- the handle to the TE scrap 

- the resource type 'TEXT' 

- the value variable theOffset, also 
defined in FrontEnd. 


We assume that there is only TEXT type scrap in the 
clipboard, so theOffset (which tells you where in the clipboard 
the desired type of resource starts) won't interest us. After the 
call, the TE scrap will contain whatever TEXT Scrap was in 
the clipboard. 


put.tescrap and get.tescrap will now have to be built into the 
code that defines our editing window. put.tescrap is installed 
into the window's activate action vector. No vector is provided 
in NEON to handle deactivate events, therefore we redefine the 
disable: method for that window so that it includes get.tescrap. 


You might now want to install just these changes into last 
month's example, then run the program and open the note pad. 
Now cutting text out of the note pad (using ctrl-X), clicking 
the edit window and pasting it there (using the TEmenu) 
should give the correct results. The opposite transfer should 
work, too. 


In order to install the serial I/O support and simplify the 


whole application somewhat, we'll use the multitasking that 
is provided in the NEON source files. Let me first say some 
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| words about how multitasking can be achieved under NEON. 


Multi-tasking the NEON way 


The NEON system supports a simple form of 'concurrency' 
(contained in the file Tasks that is part of the NEON system). 
Tasks redefines the null event vector NULL-EVT in such a way 
that it sequentially executes a set of words that are contained in 
the Ordered-Col list tasklist (This feature is not described in the 
first release of the manual). To use the multitasking support 
simply type // tasks . 


A new task is added to the tasklist by putting its cfa on the 
stack and calling addtask, it is removed again from the list by 
calling killtask with the task's cfa on the stack. So instead of 
redefining the event handler to include a call to TEIdle and 
cursor adjustment (as we did last time), we can simply define 


: idle.text 
idle: mytext adjust.cursor ; 


and then put the cfa of this word into the task list by saying 
'c idle.text addtask 


This will make the caret blink and give the cursor the correct 
shape while the main event loop can be kept in the simple 
form given in the NEON manual 


begin key makeint key: mytext again 


where the makeint comes in because TEkey expects a 16-bit 
integer on the stack. 


What is done here is not true multi-tasking, of course. Each 
word that is put into the task list is executed all the way to its 
end before the next 'task' becomes active. True multi-tasking 
would include some means to leave a word before it is 
finished, saving the task's parameters so that it may be 
resumed where it was left. 


One way multi-tasking can be done, for example, is to issue 
interrupts at regular intervals (by some real-time clock or, in 
the Mac, through the vertical retrace), and on each interrupt 
switch tasks. At this point one would save a copy of the task's 
register status in an area local to that task and proceed to the 
next one. Another possibility is that the task itself calls the 
scheduler to switch to the next task at certain strategic points - 
like when a character is being output to the screen. 


The way VBL tasks are handled in the Mac is an example of 
the first method [see also the article by Bob Denny in 
MacTutor V1#9]. The problem on the Mac is that the time 
allocated for a VBL task cannot be too long. All tasks within 
the VBL task queue must complete before the next vertical 
blanking interrupt comes in (which is 16.67 msec). Here 
again, there is no possibility to leave a task in the middle of 
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execution and jump to another one. 


An example for the other method (the task itself calls the 
scheduler, which activates the next task) is the way desk 
accessories are handled, because here you will call SystemTask 
from within your application each time you think the desk 
accessories should get something to eat. However, the DA's 
Control routine will have to execute all the way until it is 
finished - no interruption possible -, so in this case we have a 
master task (the application) which calls slave tasks (the desk 
accessories). 


A full implementation of the second method of task 
scheduling has been achieved in a new Forth system - Machl - 
which has been advertised in this journal and which I am 
going to review in the next article. This system - under Forth - 
is almost as close as you can get to true multitasking on the 
Macintosh; watch for some new exciting information next 
month. 


For the time being, we will have to stick to the constraints of 
the NEON multitasker, which means that words installed into 
the tasklist have to be short in execution because they will 
have to finish before the next task gets its turn. The idling 
routine is fast enough so that you don't notice any annoying 
delay. 


Serial port handling 


Another task that we will put into tasklist is a routine that 
will watch for characters to come in through the serial port and 
put them into the TE record wherever the insertion point is. 
Then we may - optionally - send the keystrokes not directly 
into the TE record, but to the serial output port and convert 
our editing example into a terminal emulator. 


The listing shows how to do it. Serial port handling is 
contained in the NEON source file drvr and serial, so these 
will have to be loaded first. We define modin and modout for 
the serial input and output ports and initialize them to 8 data 
bits, 2 stop bits, no parity and 300 baud. (Yes, unfortunately 
this program will handle only 300 baud, because no handshake 
has been added yet. You may use it at any speed, but have to 
watch for characters getting lost.) 


The init: , config: and baud: methods will set the configuration 
word of the port object, but not actually reconfigure the serial 
port itself. This is done by reset:, which may be used only 
after sending an open: to the port (otherwise -> bomb). 


We implement the input and output handlers to work 
asynchronously, using the methods readNW: and writeNW: 
provided by the system. These routines need the pointer to a 
completion routine as a parameter. The completion routines 
are defined using the NEON word :proc (note that you may 
never execute a :proc directly, but may only pass it as a 
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parameter to a toolbox routine). 


A :proc should be short, and therefore the routines only set 
flags that indicate that something has been received in the 
buffer or that the port is ready to transmit another character. 


getone and typeone are the words that are used to read and write 
the serial port. getone does absolutely nothing as long as no 
character has been received; otherwise, it inserts this character 
into the TE record at the insertion point and starts the next 
asynchronous read. typeone will wait until the output port is 
ready to send data and then initiate an asynchronous write. 


The background serial read is installed into the task list by 


'c getone addtask 


and when a character is typed out using typeone, the echo will 
be inserted into the TE record at the right position (assuming 
that the modem port is connected to some other system that 
supports full duplex communication). 


I have provided two routines that let you change between 
typing text into the TE record locally and doing full duplex 
communication. Another menu -localmenu- is provided to 
switch between these two modes. The revised menu text is 
printed in listing 2. 


This terminal emulator is now ready to capture text files 
through the serial port and transferring them through the 
clipboard to other applications. 


Coming up: the review of the multi-tasking Forth system 
Machl; a revision of the decompiler that can be used on 
NEON words and objects; and more. 


Listing 1: Text Edit in NEON with scrap handling and serial 
support 


\ application template example 
\ added scrap handling and some serial support 
V Cc) J. Langowski 1986 for MacTutor V2#3 


( te scrap to desk scrap copy, uses definitions from frontEnd 
) 
hex ABS constant tescrap.len 


AB4 constant tescrap.handle 
960 constant scrap. len 
decimal 


: put.tescrep ( copy te scrap to desk scrap ) 
tescrep.len -base w8 ( scrap available? ) 
if Ø call zeroscrep drop 
Ø tescrep.len -base wê txtype 
tescrap.handle -base @ òptr *base 
call putscrap drop 

then 


: get.tescrap ( copy desk scrap to te scrap ) 
scrap. len -base @ ø> 
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if Ø tescrap.handle -base @ txtype abs: theOffset 


call getscrap 
tescrap. len -base W! 
then 


P 


\ revised version of class editwindow. 
V some of the previously defined words 
\ are needed in this class 


‘Class editwindow «super ctlwind 
TErecord text 
var TEscrollbar 
int position 


:M. teinit: new: text ; 

:M settext: settext: i ;M 
:M terec: addr: text M 
:M key: key: text “M 
:M idle: idle: text ;M 


:M act: act: text ;M 
\ deactivate has to be handled explicitly by disable: 
\ for correct scrap handling 
:M deact: deact: text ;M 
:M diseble: deact: text ‘put. tescrap 
disable: super ;M 


:M click: click: text ;M 
:M cut: cut: text ;M 
:M copy: copy: text ;M 
:M paste: paste: text ;M 
:M getcont: getrect: self swap 15 - swap ;M 


\ draw: redraws window, recalculates text boundaries 
:M draw: getvrect: self calc.scroll. length 
16 swap size: [ obj: TEscrollbar ] 
moveto: [ obj: TEscrollbar ] draw: super 
getcont: self setdest: text 
getcont: self setview: text 
recalc: text 
Ø get: [ obj: TEscrollbar ] -1 * scroll: text 
getrect: self put: temprect 
abs: temprect call invalrect 
(abs) call beginupdate update: text 
Cabs) call endupdate 


we 


x x PERLE x 


release: release: text dispose: TEscrollbar ;M 

setcr: setcr: text ;M 

showscr: show: [ obj: TEscrollbar ] ;M 

classinit: heap? Vscroll put: TEscrollbar ;M 

initscroll: getvrect: self calc.scroll. length 
addr: self new: [ obj: TEscrollbar ] 


` 


scroll: 
dup +: position Ø swap -1 * scroll: text 


oe We 
== 


adjust: get: [ obj: TEscrollbar ] 
get: position - scroll: self 


:M getscr: obj: TEscrollbar ;M 
; class 


V now setup serial support for window 
port modin port modout 
90 init: modin Ø 1 init: modout 
300 baud: modin 1 8 Ø config: modin 
\ the next line isn't really necessary, 
\ since the control routines work on both ports 
\ simultaneously, anyway... 
308 baud: modout 1 8 Ø config: modout 


Open: modin Open: modout 
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reset: modin reset: modout \ local/line switch 
1 value linesw 


Ø value rxfull Ø value txempty : local Ø -> linesw ; 
0 variable serbuf : online 1 -> linesw ; 
:proc inputdone 1 -> rxfull ,proc : Start.edit 
:proc outputdone — 1 -> txempty ;proc begin key linesw 
if typeone else mekeint key: mytext then 
V define main editing window again 
editwindow mytext i 
\ routines for background tasks 2 menu localmenu 
: edjust.cursor 3 menu TEmenu 
word? where: themouse pack 1 menu filmen 
getcont: mytext put: temprect 
abs: temprect call ptinrect wordd rect edw rect edest rect eview 
if ibeamcurs else call initcursor then 50 50 400 250 put: edw 
j 9 9 380 240 put: edest get: edest put: eview 
: idle.text : main " TEmenu. txt" getmtxt 
idle: mytext adjust.cursor ; edw " Test Edit Window" docwind true true 
new: mytext initwind 
\ serial i/o for TE record call teinit 
: getone Ø abs: edest abs: eview teinit: mytext 
rxfull if 32 32 500 300 true setgrow: mytext 
9 -> rxfull 10 10 500 300 true setdrag: mytext 
serbuf cê dup 10 = Ø setcr: mytext  initscroll: mytext initct] 
if drop Ø then \ remove linefeeds " Text Edit Window, example MacTutor V2#3 (c) 1985 J. 
makeint key: mytext Langowsk i " 
‘c inputdone serbuf 1 readNW: modin settext: mytext 
drop \ get rid of fcode Ø 2000 putrange: [ getscr: mytext ] 
| then Select: mytext set: mytext 
j ‘c idle.text addtask 
1-> rxfull 1 -> txempty 
: typeone 'c getone addtask 
txempty if start.edit 
serbuf c! P 
‘c outputdone serbuf 1 writeNW: modout 
PT V junk fcode Listing 2: Menu Text file for example 
en 
; APPLEMEN 1 
"$14" 
"About Neon™..." about 
\ action words, changed w/multitasking support Cee tee A ond 
: myact get.tescrap act: mytext ; "RES" DRVR \ get desk acc 
: ciao "NN" 
‘c getone killtask FILMEN 256 
'c idle. text killtask File" 
select: fwind set: fwind Quit" bye 
release: mytext put.tescrap quit 
; TEMENU 261 
: mycont where: fevent g-)1 false makeint “TEMenu" 
click: mytext ; “Cut /X cut 
: initwind «[ 4 ]> 'cfes ciao myact null mycont “Copy/C COPY 
actions: mytext -Paste/V" paste 
: | LOCALMENU 262 
: inup get: [ getscr: mytext ] 18 - Terminal". 
put: f getscr: mytext ] adjust: mytext ; “Local” local 
: indn get: [ getscr: mytext ] 10 + "Line" online 
put: [ getscr: mytext ] adjust: mytext ; \\\ 
: pgup get: [ getscr: mytext ] 100 - XXX 
put: [ getscr: mytext ] adjust: mytext ; 
: pgdn get: [ getscr: mytext ] 100 + 
put: [ getscr: mytext ] adjust: mytext ; 
: thmb adjust: mytext ; 
: initctl «[ 5 P» 'cfas inup indn pgup pgdn thmb 
actions: [ getscr: mytext ] ; 
\ menu handlers 
\ Edit menu 
: cut cut: mytext ; | 
: copy copy: mytext ; ——- 
: paste paste: mytext ; Cd! 


(on a" = oN 
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Threaded Code: Mach I 
A Multi-tasking Forth System 


“Subroutine threaded Forth - the Mach 1 system" 


This time I am going to introduce to you a new Forth-83 
system that I recently got to review. This system is 
implemented in a somewhat different way compared with 
MacForth, NEON or other Forths, so let me digress a little 
and make some comments about Forth implementations on 
68000 based systems. 


As most of this column's readers know, ‘threaded code’ 
means program code that is organized in a very hierarchical 
manner; a 'main program’ or colon definition consists of a list 
of words that describe other lower-level definitions that in turn 
are lists of even lower level definitions and so on ... until one 
arrives at the definitions of the very lowest level that are 
directly executable machine code (See Figure 1 below). 


How do Forth systems implement this structure? The 
definition of every Forth word, colon definition, variable, etc. 
contains one short piece of executable machine code at the 
very beginning. This is called the code field and determines in 
which way the information following it is handled. For 
example, in a colon definition in MacForth, the code field 
contains a TRAP 4F (V2.0) or 
TRAP #E (V24) instruction 
that jumps to code that in turn: 


- pushes the instruction pointer 
(A3) on the return stack, 

- Sets the instruction pointer to 
the address of the first word of 
the new definition to be 
executed, 

- jumps to the NEXT routine 
which executes the tokens that 
follow the code field. 


MYWORD1 £ 
EXIT 


Mac Forth is an example of 
‘token threaded Forth' which 
means that the numbers 
following the code field are not 
valid addresses of other Forth 
Words, but 'tokens' that are to be 
converted into addresses by 
some algorithm. In Mac Forth, 
positive token values are 
interpreted as offsets from a base 
pointer (A4), while negative 


O The Complete MacTutor, Vol. 2 


Jórg Langowski 

EMBL, C/O I.L.L. 
Grenoble, Cedex, France 
MacTutor Editorial Board 


S 


MACH v1.0 


token values are negative offsets from the top of application 
space (A5) into a token table, where the 32-bit address of the 
Forth word is found. The token table is used to handle 
programs that exceed the 32 K address space that can be 
handled through the first method of addressing. 


The advantage of MacForth's and similar structures is that 
we need only 16 bits for each word compiled into a definition. 
The disadvantage is the limited address space (32K) for the 
simple A4-indexed addressing mode and the need for a token 
table to convert tokens into addresses that lie outside the 32K 
addressing region. Time is lost on each NEXT loop by having 
to test whether the token is negative or positive, then 
eventually by accessing the token table ( See Figure 2 next 
page). 

The Forth implementation that was used to create NEON 
does not need a token table since each word uses 32 bits, but 
more space is used in the compiled definitions that way. 

Fig. 3 gives a summary of some possible addressing 
modes for Forth interpreters with their execution times (in 
system clocks, from the MC68000 manual). Some of these 
examples have been taken from a Dr. Dobb's Journal article by 
Joe Barnhart, 'Forth and the Motorola 68000', DDJ 83 (1983) 
18-26. 


(mad — 


move (a7),-(a7) 


Fig. 1: Structure of a threaded-dode program 
(example MacForth K2.4) 
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MacForth does not conform to any of the 'pure' definitions 
here, but (cf. Fig. 2) is a mixture of a base-offset direct word 
and base-offset indirect long threaded code (with an additional 
branch required). 


You see that in all the examples given the inner interpreter 


MOVE 
BMI 4 
JMP O(A4,DO.W) 
MOVE.L 0(A5,D0.W),D1 
JMP 0(A4,D1.L) 


(A3)+,D0 


Fig. 2: NEXT routine (inner interpreter) 
of MacForth K2.4 


Times in clock periods. 


requires considerable overhead to 'set up' the forth words for 
execution. 


Additional overhead is created by the execution of the 
small piece of machine code starting at the CFA. In MacForth 
this is a TRAP instruction (38 cycles) plus three lines of 
assembly code that the trap vector points to (32 cycles). 
Counting everything up, execution of one colon-defined Forth 
word requires 100 or 120 cycles under MacForth, depending 
whether or not the token table has to be accessed. In a system 
like NEON, the CFA does not contain a trap, but a JSR to a 
routine that sets up the inner interpreter, with a similar 
amount of time involved. 


One solution around this problem is to code time-critical 
things in assembly language, so that the whole definition is 
made up of executable 68000 code, starting with the code field. 
I have given an example for this in MT V1#9 by defining 
macro words that compile inline code into a definition. The 
speedup was of the order of 50% for MacForth. Of course, if 
you write inline macros, you are not really creating threaded 
code, but linear code, and the size of the definition tends to get 
rather large. 


Still, there is another way to create threaded, i.e. 
hierarchical, code that does away with the needs for an 'inner 
interpreter loop completely, since the threaded code will be 
directly executable 68000 machine language. This sounds 
strange, but is actually very simple to achieve. The keyword is 
'subroutine threading. As you saw from the inline code 
example, we can do without a 'code field' by just starting to 
execute our definition at the very beginnning, provided it is all 
bona fide 68000 code. Now, all we have to do is to persuade 
the Forth system not to compile a list of addresses into a 
colon definition, but a list of JSR (addr). This way, we don't 
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sum: 
30 clocks (branch not taken) 
50 clocks (branch taken) 


need the inner interpreter at all, Forth instructions are 68000 
instructions; the subroutine return stack, in this case, is the 
normal 68000 stack, pointed to by A7 (Mach 1 uses still a 
different stack for loop indices, more about that later). 


The speed increase over the 
previous examples is 
considerable, with only 18 
cycles of overhead for the JSR 
instruction if the jump is taken 
within the segment, or 30 
cycles for one more .JMP if a 
jump table has to be used to 
branch to a different segment. 
This is one-fifth to one-third of 
the overhead of any of the other 
implementations given on the 
next page in Fig. 3. 


Actually, subroutine 


threadin ives us a, Forth 
compiler that creates native 68000 code S which won't even 


need a runtime Forth nucleus, but will nicely execute by itself. 


Drawbacks of this strategy: A7 cannot be the Forth data 
Stack pointer any longer, some other register has to be used. 
This does not really create a problem as long as one stays 
within Forth; the 68000 couldn't care less which stack pointer 
you use for passing arguments between routines. Toolbox 
routines, however, expect their arguments on the A7 stack. 
Their calling sequence, therefore, becomes a little bit more 
complicated - and more time consuming - in a subroutine- 
threaded Forth implementation, since all the arguments have to 
be transferred from the data stack to the A7 stack first, then 
any result has to be swapped back from the A7 stack to the 
data stack. Also, since toolbox calling should be transparent to 
the user, the Forth compiler should know about the parameters 
that all the toolbox traps expect and create the 'glue' code 
automatically. 


Subroutine-threading, considering all the pros and cons, is 
certainly one of the more elegant ways to implement Forth. 
Given a good compiler, the user will see no difference to a 
‘classical’ Forth, except that the resulting code runs faster by a 
factor of (approximately) two. The 68000, with its ability to 
use any address register as a stack pointer, is especially suited 
for this kind of approach. 


Such were my thoughts at the end of last year, and I had 
started doing some experiments implementing my own Forth 
on the Mac, which was going to be subroutine threaded. That 
was when I received a letter which described a system that did 
all the things that I just mentioned, and some more. With the 
effect that I realised that perhaps in a year or two my own 
efforts would get me to where others had gone already. Too 
bad. 
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The letter came from a company called Palo Alto 
Shipping, and they had developed a system called Machl, a 
subroutine threaded Forth-83, multi-tasking above all. After a 
long introduction, let us jump right in the middle of things 
with a description what Machl is and what it can do. 


MOVEA (A3)+,A0 8 
JMP (A0) 8 
16 


MOVEA.L (A3)+,A0 
JMP (A0) 


MOVEA (A3)+,A0 MOVEA.L (A3)+,A0 
MOVEALL (A0)+,A1 


JMP (A1) 


8 
8 
8 
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MOVE.L (A3) «,DO 


a MOVE (A3)+,D0 8 
4 JMP 0(A4,D0.L) 


| JMPO(A4DO.W) 14 


MOVE (A3)+,00 
‘| MOVE 0(A5,D0.W),D1 
| MP 0(A4,01.W) 


MOVE.L (A3), DO 12 
MOVE.L0(A5,D0),D1 18 
JMP 0(A4,D1) 14 

44 


Fig. 3: addressing modes for Huh interpreters 


The Mach1 system 


With my evaluation package I got one disk and a 
deceptively small handbook. Opening the latter revealed a 
phrase on page IV that I wish to see on more software 
products: All rights reserved. Nothing more, no legalese for 
which you need to take courses to understand, just a simple 
copyright notice as you would find it in any serious textbook. 
Being a strong adherent of Jerry Pournelle's policy concerning 
Silly Licensing Agreements, I found this part of the manual 
extremely sympathetic. Later, it is explicitly said that you 
may make as many backup copies as you like and use them - 
one at a time only - on any machine you like. Good. 


The handbook gives a short introduction to Forth and 
refers beginners to Starting Forth for a good tutorial. The 
system is Forth-83, with some additions. Of course, these 
additions are where the fun comes in, so here are the main 
features that make Mach1 comfortable: 
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- program loading from normal text files, no blocks. 


- local variables in a local stack frame created by the 
LINK/UNLK instruction. 


- a floating point package for access to the SANE library. 
Unfortunately, no fast 32-bit floating point (only Fortran 
has it so far). 


- words that give easy access to the MacinTalk speech 
synthesizer, which comes with the system. 


- vectored input/output (e.g., if you really want, you could use 
the system from a serial terminal). 


- an assembler that recognizes standard Motorola syntax 68000 
code, 


- a debugger/disassembler/decompiler that can be used like 
Macsbug and recognizes almost the same commands, but at 
the same time decompiles Forth words. 


- the possibility to save the system with all definitions that 
you added so that you can quit and resume work without 
having to reload everything. This is called 'snapshot' in 
MacForth and 'workspace' in Machl. 


- a very easy way to create stand-alone 'turnkey' applications 
which contain a stripped-down version of the Forth runtime 
system and are not too large. These applications may be sold 
without any additional licensing fees. 


- true multi-tasking with an arbitrary number of tasks. 


The toolbox is accessed through the word CALL which 
(on compile) looks up the necessary parameter setup for the 
trap, swaps them from the data stack (A6) to the subroutine 
stack (A7) and calls the trap. Three traps cannot be called, 
UnlodeSeg and LodeSeg - this is understandable because of the 
heavy use of the segment loader by Mach itself - and 
TECalText, which I wasn't able to figure out why. 


For the creation and management of windows, controls, 
and menus, sufficient support is given through high-level 
words in the Machl system. There is a 'templates' menu with 
which you can define a window's characteristics in a dialog 
box, and the Forth commands to create that window will be 
automatically copied to the clipboard; same for menus and 
controls. Like in NEON, you may load from the clipboard. 


Machl is packaged with the switcher and MDS Edit. 
You're supposed to set up the system in a way that you can 
switch between Edit and Machl for development. I found 
myself pretty soon trashing Edit and using the Editor desk 
accessory for writing programs, which overall is faster, though 
Edit does a better job of formatting. 
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Multi-tasking under Mach1 


Before we get to the program example, let's take a quick 
look at the multi-tasking features of Machl. You will soon 
see that multi-tasking is so essential in this system that the 
style of programming in Mach] will be quite different from 
other Forths. 


Under Machl, you may define tasks. Each task has some 
private stack and user variable space assigned. Tasks are 
arranged in an endless chain, with each task containing a 
pointer to the next task in the chain at the base of its user 
variable area. Just below this pointer is a word that contains 
the status of the task, SLEEP or WAKE. This word actually 
is executable 68000 code; if the task is aSLEEP, the code 
looks like 


4EF9 XXXX XXXX JMP next task, 
if it is aWAKE, it is 
4E40 ---- —-- TRAP #0. 


So tasks that are dormant will just be skipped by a jump 
to the base address of the next task; active ones execute the 
trap instruction, which falls into a routine that restores the 
task's register file and continues where it quit the last time. 
Any task will execute until the word PAUSE is encountered, 
at which point the local registers will be saved and execution 
transferred to the next task. 


PAUSE can be compiled into a task's code at strategic 
points, for example in a loop that is part of a lengthy 
calculation. Also some built-in words (mainly I/O, like 
EMIT) contain a PAUSE. The requirement for the task to call 
the scheduler, instead of the scheduler switching tasks 
automatically, is the only thing that distinguishes Mach] 
from a full implementation of multi-tasking. So multi-user 
would be not practical, because if one user entered into a 
pauseless loop, the others would be cut off; but for single-user 
multi-tasking this system works very well. 


I have written a background task that acts as a printer 
spooler for this month's example. One of the problems with 
Machl is multiple file handling; each task can only handle one 
open file at a time (from how I understood the manual). 
Therefore, multi-tasking comes in automatically if one wants 
to work with several open files (I've heard that this is done 
sometimes...). 


Another drawback is that the file handling routines cannot 
accept a file name string as an external parameter; it is 
compiled into the definition that calls the file routine. 
Therefore, when a new spool file is opened, my program 
resorts to a kludge, storing a unique 4 digit decimal number 
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into the appropriate position in the word's code (which I was 
able to find with the debugger). 


The example below creates a task, spool task, that 
executes spool in the background. This is an infinite loop that 
looks for the numbers of spool files contained in a list; if the 
list is non-empty (list.busy), it will open the spool file with 
that number and print it until it encounters a zero byte (end-of- 
file for a text file). The spool file is not deleted, so your disk 
might fill up rather quickly; reason is that there is no 
predefined word for deletion of files in Mach1, and I was too 
lazy to write one. 


If you have Machl, load this program, create a second 
active window, like the "Skylight" window in the example on 
page vi of the manual. Then say new spool in the main 
window, which will create a new spool file, open it and 
redirect the output to both the file and the window. Click the 
second window and do the same there. Now you can create 
output in one of the windows, e.g. by 7FREE or WORDS, let 
the thing go and do some output in the other window. When 
you close spool in any window, the background task will 
automatically start printing the spool file while you can 
continue doing (almost) whatever you like in one of the 
windows. 


Sieve benchmark 


The famous Erastothenes Sieve (see back issues of this 
magazine, e.g. V1#9) executes in 12.8 sec (in my hands). This 
is almost twice as fast as MacForth or NEON (both slightly 


above 20 sec) and only twice as slow as compiled C of average 
quality. 


Assembler 


The Assembler contained in Machl accepts standard 
Motorola syntax. Words defined under Mach1 may be used in 
the operand field of assembly statements, e.g. in a JSR. One 
important feature is the automatic creation of inline code; 
when you say MACH after defining a word, the compiler will 
insert the code comprising the word into other definitions, 
instead of compiling a JSR to the code's address. Simple 
words like DUP and SWAP are defined this way; when you 
disassemble a definition containing these words, you will find 
no JSRs, but code that does DUP and SWAP directly. 


Summary 


This review, by no means complete, should have given 
you a flavor of Mach1 and what can be done with it. I am 
impressed of the speed of the code created; an easy-to-use 
assembler and debugger and the MACH inline code feature 
help speeding up the system even more. For speed 
considerations, a fast 32-bit floating point package would be 
desirable. 
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The multi-tasking feature is so easy to use that one often 
splits up programs into tasks when one wouldn't have thought 
about doing so in other languages. Due to the intrinsically 
high speed (subroutine threading) the scheduler also doesn't 
create too much overhead, if one uses PAUSE with 
consideration. 

The vocabularies that come with the system are rather 
small compared with other systems; nevertheless, full Forth- 
83 has been implemented and all the necessary things are 
there. With the MACH macro feature, many of the 'combined' 
words such as IC! are not needed anymore. The existing set of 
words is explained very thoroughly in the manual, going into 
depths of the assembly coding where necessary. Dictionary 
structures, memory maps, task structures all are explained in 
detail. 

Access to the Macintosh toolbox routines is convenient, 
and the template facility to set up standard windows and 
controls comes in very handy. There is even a special kind of 
scroll bar that will automatically resize with the window. 

Stand-alone application may be created very easily, 
spanning several code segments if necessary. The applications 
need no run time kernel or library to run, which is nice (in 
fact, I consider it almost essential). The right to sell Mach1- 
created applications is contained in the purchasing price of 
$49.95. 

Still, there are some bugs in the system. The debugger 
will work only once with the debugging switch, using the 
switch a second time crashed the system (in my hands). Also, 
some instructions are not disassembled correctly. Those bugs 
(and probably others that I haven't found) are nothing more and 
nothing less than one would expect for a freshly released 


system and I expect them to be fixed soon (upgrade charge $5). 


The file handling system is not as convenient as it could 
be. Multi-tasking makes up for many of the inconveniencies, 
but not for all of them. A reasonable set of 
open/close/position/delete routines that accept stack input 
Should be included. Also, the TECaltext trap should be 
accessible through the normal CALL mechanism. Finally, a 
fast floating point package would make a real nice addition. 

All in all, I can highly recommend Machl for both Forth 
beginners and developers. What intrigues me most is that with 
a rather small vocabulary one has a system at hand that makes 
near optimal use of the Macintosh's special features and is 
fast, too. One last recommendation to Palo Alto Shipping: 20 
instead of 2 pages of index would improve the handbook 
dramatically. 


( Mach 1 background printer spooler ) 
( € J. Langowski / MacTutor Feb. 1986 ) 


only mac also i/o also forth 
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: wkg_spool working" spool] .###8" ; 
: cre-spool create" spool sans" ; 
: use-spool using" spool. #888" ; 


variable f ilecount 

variable printlist 400 vallot 
variable print.ptr 

198 user active.spool 


: file? filecount 8 ; 

: print print.:ptr 84-8; 

: incr.file filet 1+ filecount ! ; 

: incr.print print.ptr 6 4 + print.ptr ! ; 

: decr.print print.ptr @ 4 - print.ptr ! ; 

: reset.file 1filecount ! ; 

: reset.print printlist print.ptr ! ; 

: add.spool ( n - D 
printlist print.ptr @ 

do i4-6@ i ! -4 +loop incr.print 

printlist ! ; 

: list.busy print.ptr @ printlist © ; 


11 constant *#offset 
€ offset from beginning of file routine to file name ) 


: wkg_spool® (n-)2« 919 9 ( four digits ) 

['] wkg_spool *#offset + swap cmove 

( change file name, append number ) 
wkg_spool ; 

: cre_spool® ( n - ) «t 8 m s s s) 

['] cre_spool ##offset + swap cmove cre.spool ; 
: use-spool ( n - ) «8t s 9 s sn 8) 

[') use_spool *#offset + swap cmove use_spool ; 


: new. Spool 
incr.f ile 
filet cre spool? filet wkg_spool# 
filet active.spool ! 
.. Your spool file is spool." filet . cr 
file output 12 emit C form feed ) 
." SPOOL FILE * " filet . cr 
console file * output 


) 
: close.spool console output close-f ile 
active.spool 6 add.spool ; 


: print file 8 
begin dup virtual cê dup while emit 1* repeat 
2drop ; 


: print. spool 
list.busy if 
print* decr.print use.spoolt disk 4 + we 
not if print file close-file 
else 18 call sysbeep then 
then ; 


400 19000 background spoo! task 
spool_task build 
hex 
: Spool activate 
IccBa mode2 comm2 output 
begin print_spool pause again 


decimal 
reset .file reset.print 
Spool.task spool 
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Threaded Code 
Updates for Machl and Neon 


"In Our Mail" 


This time, I have no specific subject to cover, but would 
rather like to address a few points that came up while 
browsing through my mail lately. Also, I want to inform you 
on updates of NEON and Machl that just came in. (Judging 
from the productivity of some of the developers, the next 
updates will probably be out even before this comes back from 
the printer's...) 


We received a letter from Finland; Juri Munkki from 
Helsinki sent the following interesting note: 


"I received my HD 20 yesterday and I found some 
problems with using it for Forth development using MacForth 
Level 3. The problems arise when trying to access files from 
directories outside the Forth folder [this seems to be one of the 
standard problems in HFS. J.L.]. I was very glad to see that 
my terminal program worked correctly with HFS and used that 
knowledge to add a new command to MacForth. 


MacForth activates windows automatically when an 
activation event is received. This is not desirable when 
returning from a standard file-call because it interrupts the 
execution of the calling program. Before receiving Level 3, I 
used a special window for calling the standard file package and 
used two different activate procedures. Level 3 documentation 
explained the Event.Table and I was capable of simplifying the 
calling of these extremely important routines. 


The main reason my program worked was that it used 
PBSetVol to change the default directory. ...... This simple 
technique of calling SetVol after SFGetFile and PutFile 
allows me to use standard MacForth file commands without 
any modification of the internal structure FCBs. 


The routine below [Listing 1] fits in one block (if left 


without comments) and is very helpful in using the HFS 
folders. " 


Listing 1 : Select directory, by Juri Munkki 


€ Directory Mount utility) (C 011086 
) 

create SFReply 76 allot 

SFReply 76 erase € standard file reply record) 

create OurParams 32 allot 

OurParams 32 erase ( our param block) 

hex A815 os.trep SetVol  ( PBSetVol OS trap ) 


A9EA wot Pack3 C standard file package) 
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MACH v1.0 


Jorg Langowski 

EMBL, C/O I.L.L. 
Grenoble, Cedex, France 
MacTutor Editorial Board 


variable act.ev.proc ( standard action for activate ) 


: seldir € lets the user choose a default directory ) 
activate.event 2* event.table + w@ act.ev.proc ! 
( save old activate.event vector ) 

Ø activate.event 2* event.table + w! 
( disable vector temporarily ) 


00400040 " " Ø -1 Ø wbury Ø Ø sfreply 2 pack3 


( call SFGetf ile) 
act.ev.proc @ activate.event 2* event.table + w! 
( reset activate vector) 


SFReply cê if Cfile was selected) 
SFReply 6+ w@ OurParams 16 + w! 
OurPerams SetVol then 


d 


axe SetVol axe Pack3 axe act.ev.proc 
axe SFReply axe OurParams 
decimal 


“Just type SelDir and choose a file from the directory you 
want to work with. This directory is automatically vref 0 and 
can be shown by typing 0 dir. I thought that you might find 
this information useful to some MacTutor readers. ... " 


Yes, we do, thank you for that contribution! I tested that 
routine - not using HFS, since I don't have 800K disks or a 
hard disk yet - but to change the default drive. After executing 
SelDir (e.g. on a file in the external drive), both 0 dir and 2 dir 
will display the external directory, and files without directory 
prefix will be looked for on the external drive. Saves a lot of 
hassle when one loads files from the external drive that 
include" files that are also on the external drive. 


Indirect recursion and deferred execution 


Another letter comes from Steve Pothier in Tucson, AZ, 
asking a question about recursion in NEON. I made a 
comment in the NEON article (MT V2#1) about the use of the 
forward declaration in recursion, which I did not further 
explain, so here goes: 


As a matter of fact, simple recursion is generally allowed 
in NEON, while this is not the case in MacForth. As said in 
the mentioned article, one can circumvent this problem by 
resetting the smudge bit during compilation. Mach1 has the 
word recursive built in which does exactly this job, so the 
corresponding definition of the factorial would be: 


: factorial | € Mach 1 version ) 


recursive 
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dup if dup 1 - factorial * else drop 1 then ; 


So we're pretty fine in any kind of Forth doing direct 
recursion, that is to say referencing a Forth word from within 
its own definition. However, indirect recursion is a different 
ballgame. If we want to reference word A from word B, which 
contains a reference to word A in its definition, we will have 
to reference one of the two words before it is actually defined. 
This is, of course, not possible in Forth. But the problem can 
be solved. 


Lets assume we define routine A first, then routine B. 
Then the only way to refer to B from within A is to create a 
vector B.vect before defining A, referring from within A to 
B.vect instead of B, and setting the vector after having defined 
B. Lots of As and Bs here, an example will illustrate: 


create B.vect ( and do something with it ...) 
. code to initialize the vector .... 


Gr ahateak 
poe B.vect ( B is called here ) 
"Boece 
T A ( may be called in the normal way ) 
. code to setup B.vect so that it executes B when 
called .... 


How do we do this in practice? NEON has the forward 
declaration built in. In case one needs to refer to a word that 
cannot be defined yet, one can 'pre-declare' this word by saying 
forward B and then using this definition of B in any other 
words following it. When one is ready to define B, the special 
defining word :F together with ;F is used to resolve the 
forward reference. As long as this has not been done, any 
attempt to execute B will result in an error message. The 
example from above then looks like the following in NEON: 


forward B 


B CB is called here just like any word ) 


A ( called in the normal way ) 


°F 
Pi 
( forward reference is resolved after this definition) 


Standard Forth (-79 or -83) does not have a forward 
declaration built in. MacForth and Machl don't have it. 
MasterFORTH has defer, which does a similar thing as 
forward, defining a word whose action will be defined later. 
defer and related words are explained in the book 'Mastering 
Forth' that comes with the MasterFORTH package: 


: undef .error ." not defined yet! " cr ; 


: defer create ['] undef.error , 
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does? 6 execute ; 
: is ' >body ! ; 
defer is a compiling word whose runtime action is to 
execute the vector that it contains. Initially, this vector is set 


to the address of a warning message that is printed as long as 
the word has not been defined yet. 


is stores the address on the stack into the body (Forth-83) 
of the word following it. This means if we define 


defer my.vector 
: test ." Hello world!" cr ; 


and then say 


' test is my.vector 


execution of my.vector will result in "Hello world" being 
printed. 


Now our indirect-recursion example from above would 
look like: 


defer B.vect 


' B is B.vect 


Notice that these definitions are for MasterFORTH; 
Mach] has a different structure (explained in my last column), 
and the definition of is has to be changed: 


: is C Machi version) ' 4 * ! ; 


MacForth has an even different structure; the 
corresponding definitions would look like: 
:undef .error . " not def ined yet!" cr : 
: defer 
create ' undef.error , 
does? @ >r ; 
is [compile] i ! : 


For MacForth, I have also given an example of Leo 
Brodies DOER/MAKE vectored execution handler (V1#7). 
DOER/MAKE, of course, allows also for deferred execution, 
e.g. 


doer B.vect 
A arate onal B.vect — uu ; 
CB rad A. — uses F 
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make B.vect B 


with the additional advantage that vectors can be made to 
execute other words from within definitions. I won't give the 
corresponding definitions of DOER/MAKE for Machl or 
MasterFORTH here; this is, as they say, left as an exercise for 
the reader. 


Upgrades, improvements etc. 


I just received updates of NEON (v 1.5) and Mach (Mach 
1.1) in the mail. Many of the bugs that were still present in 
the first versions of these systems have been removed. Let me 
just give you an extract of the information that was sent to me 
together with the updates by Palo Alto Shipping and Kriya: 


Mach 1.1 
[excerpts from the letter by Palo Alto Shipping] 
"MACH 1.1 SUPPORTS MACPLUS AND HFS 


MACH 1.1 includes support for the new trap routines 
included in the new 128K roms and works under the 
Hierarchical File System. SWITCHER 4.6 is also included. 


DEBUGGER REMOVED 


A debugger is no longer included in MACH 1 for two 
reasons. One reason is that there is currently an abundance of 
inexpensive, high quality debuggers for the Macintosh. The 
second reason is that since the debugger was written in MACH 
1, its performance was very dependent upon the integrity of 
the MACH 1 kernel. If the kernel ever became damaged, the 
debugger would often fail. The debugger chapter in the 
manual should be disregarded. [Too bad that this part of the 
system is gone. The single stepping mode with the ability to 
see Forth and machine code simultaneously was a nice feature. 
However, the debugger had its own bugs... Palo Alto 
Shipping is working on an improved version and planning to 
reinstall the debugger on future systems] 


Note that the dissassembler is still included. [from which 


the addressing mode bugs mentioned in my last column have 
been removed / J.L.] 


NEW WORDS 
Six new words which run the default event-handling 
routines when executed have been added to the MACH 1 


kernel. [to be used to stash into deferred execution vectors 
etc... / J.L.] 


The following words which support the printing manager 
have been added to MACHI: [...] 


PrCtiCall PrDrvrClose PrDrvrOpen 
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PrSetError PrError PrPicFile PrCloseDoc 
PrClosePage PrOpenPage PrOpenDoc 
PrJobMerge PrJobDialog PrStlDialog 
PrValidate PrintDefault PrClose PrOpen 


That's for the Mach1.1 update. It seems to me that with 
the extra printer support the spooler example form my last 
column could be upgraded into a real nice background spooler 
for Text and Paint files. The upgrade furthermore contains a 
second disk packed full of demos, some of which are rather 
sophisticated application examples (e.g. a TextEdit example 
and one that uses the printing routines). Also includes is a 3-d 
fractal demo that draws mountain shapes. Nice to look at. 


NEON 1.5 


The main additions to the new NEON 1.5 are listed 
below [words by Kriya Systems]: 


"Here are the functional differences between Neon v1.0 
and v1.5. [...] 


Features added: 

* Floating Point support; use "neonFP.com" 

e All source for rebuilding Neon up from the nucleus is 
released 

* New classes have been included: LinkedList, 2dArray, 
Dictionary, etc... 

* New utilities have been included: Decompile, PrintAll, 
Words, etc... 

[The Decompiler supplied by Kriya works only on Colon 
definitions. One that gives also at least some informations 
about class definitions is still a project for this column. / J.L.] 

* Neon™ v1.5 is compatible with the new Neon™ 
Assembler 

e SORT is a new word which performs a shell sort 

e $= is a new word which performs a relative compare on 
strings 

* LAND, LOR & LXOR are new words which are the 
logical counterparts to the bitwise AND, OR & XOR 

e PUSHPORT & POPPORT are new words for keeping 
graph port record pointers on the data stack 

* PARAMTEXT is a new word for use with dialogs 
which sets text substitution strings for Static and Editable text 
items 

* CALLER is a new pseudo-ivar, like SELF or SUPER, 
which late binds a message to the calling object. (This must 
be used inside a method.) 

* The fill: method has been added to String 

* À disp: method has been added to each of Picture, Alert, 
Rect & Icon 

e The putText: & getText: methods of Dialog now work 
on control items 

e The status of the cursor is now preserved during Neon 
functions 

e You may now grow the Neon window to the full size of 
a MacXL screen 
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* Compile echo now functions for modules 

* WORDS now formats it's output according to the width 
of the window 

e The Install dialog now includes the "Max Heap" button 


Bugs fixed: 

* The name field for SIGN is fixed and is now findable 

* The U* presicion bug has been fixed; (*/ & M* also) 

* PURGE has been modified to work on megabyte Macs 
* The fill: & new: methods of Array have been fixed 

e The put: & click: methods of Mouse have been fixed 

* The charOf: method of String has been fixed 

* The print: method of Timer has been fixed 

* The baud: method of Port cleans up the stack properly 


Functions changed: 

* FINFO returns a relative address 

* STDGET takes a specification of up to four file types 

* The words MLOCK, MUNLOCK & ?MLOCK now 
take the cfa of a module 

e NULL & BYE are now defined above the nucleus so 
that they may be called from menu selections defined 
through the use of getMtxt. 


[Before, it was very important when making stand-alone 
applications, to define 'calling words' for BYE and NULL, 
which were part of the nucleus, and use those 'super- 
definitions' in menu files. Otherwise, the menu handler would 
not find the NEON word corresponding to the menu item 
when the menu text was loaded at runtime, causing a crash. 
This was the reason for the crash of my text edit example in 
the Feb 86 issue; I forgot to include a new definition for 
NULL just like the CIAO definition for BYE] 


* The word FF (form feed) has been renamed to NP (new 
page) 
e QUIT now clears menu bar hilites 


* The Grep utility now prints the file name only when a 


match occurs 

e ASCII no longer shifts alphabetics to upper case 

* The grow: method of Window does not clear the 
window 

° The actions: method of vScroll has a clear: parts 

* The Apple menu now accomodates up to 22 items". 


[Other observations: 

* Quitting NEON with the Editor still open and 
relaunching from the desktop no longer causes a crash. 

* The bug in IC! (this word simply didn't work under 
NEON 1.0) is still there!. The Sieve example (see MT V1#8, 
p.18) still works only when IC! is replaced by I C!. -J.L.] 


Since I have not upgraded my systems to the large drive, 
new ROMs and HFS yet (I'm reluctant to do so as long as 
there is no working version of Fortran available for HFS), I 
cannot judge whether NEON 1.5 will work correctly with the 
new system. Any comments on this by readers will be greatly 
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appreciated. 
The fix for IC! 


Since Kriya Systems don't seem to have noticed, here's 
my fix for IC!, which makes this word work correctly (did this 
by disassembling the kernel and looking through the file with 
Fedit): 

The code that has to be fixed starts at relative address 
$13B4 (absolute $E044 in my system) in both NEON 1.0 and 
NEON 1.5: 


13B4: 2E16 MOVE.L — CA62, D7 

1386: X 568F ADDQ.L %3,A7 

1388: 179F 7800 MOVE.B — CATO*, ØCA3,D7) 
I3BC: — 2C1C MOVE.L — (A4D*, D6 

]3BE:  2E33 6800 MOVE.L — 8(A3,D6)2, 07 
1302: | 4EF3 JMP ØCA3, D7) 


For some reason, the ADDQ in connection with the MOVE.B 
does not seem to do its intended job (Can anyone help me; 
68000 machine code specialists, please). The code works if 
you change it to: 


1384: — 2E16 MOVE.L (A62, D7 
13B6:  201F MOVE.L CA7)+, DØ 
13B8: 1788 7800 MOVE.B DØ, 8CA3,07) 
13BC: — 2C1C MOVE.L CA4)+, D6 
13BE:  2E33 6800 MOVE.L CA3,D6), D7 
1302: — 4EF3 JMP ØCA3, D7) 


The way to install this patch permanently is by using Fedit or 
some similar program. Open the NEON file and search for the 
hex sequence 568F179F. Verify by looking at the code around 
it that you have really found the correct piece of code. Then 
replace this sequence by 201F1780. Now rewrite the sector to 
your disk (HOLD IT! You did make a backup first, I 
suppose?). This should give you a working IC! in your NEON 
kernel. 


Questions, comments etc. may now also be addressed to: 
LANGOWSKI@DHDEMBLS on BITNET, or, if you are 
using BYTEs BIX system, you can leave mail under 
JLANGOWSKI for me or MACTUTOR for David Smith. 


See you in a month. 


429 


Threaded Code 
Install a VBL Task with Machl 


Installing a Forth VBL Task - another CRT saver 


Bob Denny's Article on vertical blanking tasks (MT 
V1#9) has been a constant challenge to me ever since it 
appeared. It seemed that there are certain things that one just 
could not do in Forth - the installation of an independently 
running task in the system heap being one of them. After all, 
where do you put the Forth runtime support when you leave 
Forth and want the task to run? 

Another thing that would be difficult to do in Forth, for 
example, would be a desk accessory. In general, any tasks that 
will run independently and concurrently in the Mac operating 
system are almost impossible to handle with a language that 
needs a runtime interpreter to work. 

After Mach1 came in, one could sort of see the light at 
the end of the tunnel. Here was a Forth that created real 68000 
machine language output, and in principle its code could run 
anywhere without ever needing any runtime package. Maybe 
this makes some of the 'impossible' things that I mentioned 
less impossible. 

Still, Mach1 does contain runtime support. Multitasking 
is the most important one, but by no means all, even the 
LOOP of a DO...LOOP structure is compiled as a JSR to a 
kernel routine. 

The first rule for creating programs that are not only 
'stand-alone applications', but self-contained code, is to avoid 
all references to kernel routines from within the program. This 
general statement will hold for any Forth system; given a 
Forth assembler, enough patience and a good set of macro 
definitions one will always be able to write code that is self- 
contained and won't need the runtime interpreter (e.g. using 
inline macros similar to the ones defined in MT V 149, Forth 
column). Mach1 code doesn't contain too many references to 
its kernel anyway, so it should be much easier to accomplish 
what we try to do. 

Our problem is to create a piece of code that does exactly 
what Bob Denny's CRT saver does: intercepts the 
GetNextEvent trap and updates a counter to keep track of when 
the last non-null event happened, and a VBL task that looks at 
that counter and blanks the screen whenever a certain time has 
elapsed after the last non-null event. Furthermore, the 
GetNextEvent intercept routine will repaint the screen after it 
has been blanked when a new non-null event occurs. 

For the purpose of illustration, Listing 1 shows some 
Mach! code that installs a very similar screen blanker as a 
background task under Machl. This is the simple way to do it 
and will of course run only within the Mach1 system. 

Short explanation of the program: the blankout routine 
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opens a new GrafPort and paints its portRect (default size: 
whole screen) with the default pattern (black). 

This routine is installed into one background task, 
CRTsaver, that checks continuously whether the time after the 
last 'relevant' event is larger than a preset value and blanks the 
screen if it is; thereafter, it unblanks the screen when a new 
event is received. The task's infinite loop contains a PAUSE 
to give control back to the scheduler. 

The second background task, eventmonitor, checks for 
events by calling EventAvail. Whenever a 'relevant' event 
Occurs, it is intercepted by this routine and the event tracking 
counter last.action updated. 

Try and install these routines on your Mach1 system, and 
youll have a fine CRT saver. Note that the multitasking 
system is not running while the screen is dark; I did this to 
keep it completely blank. You can insert a PAUSE in the 
event waiting loop of do.blank; in that case, all tasks will 
keep running, but you'll have a small white rectangle on the 
black screen (the cursor which is still active). 


Installing the CRT saver as an independent VBL task 


The example in Listing 1 contains many things that will 
just not work independently of the Mach1 runtime package: 


- background tasks; 


- variable definitions, which are kept separate from the 
main code block; 


- JSR references to the kernel are not contained here, but 
could be easily in other tasks (as mentioned, a simple 
DO...LOOP); 


- there are certain trap calls that are incompatible with the 
VBL task mechanism; as mentioned in IM, trap routines that 
move, purge or reallocate memory may not be called from a 
VBL task, the reason being that if the task happens to 
interrupt the memory manager and then calls the memory 
manager itself, very strange effects may result. 

The list of 'forbidden' routines (IM, Addison-Wesley Vol. 
III in the appendix) is impressive, and EventAvail is one of 
them. The Quickdraw calls in blankout are also forbidden. 


- The Machl data stack is maintained through the A6 
register. In self-contained code, this register will have to be set 
up to point to a local stack area when the code is first entered. 
Also, for safety reasons the complete register file should be 
saved on entering and restored on exit. 
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An impressive list of restrictions; however, the example 
in Listing 2 shows that it is not that bad after all. 

First, we may not use variables anymore. Any variable 
Storage space should be defined within our piece of code. This 
can be done using create or header. References to variables thus 
defined must be through ['] (in colon definitions) or ' (in direct 
execution). If a create variable is referenced by name in a colon 
definition, a JSR to its code is compiled. create's own code 
again references the kernel and therefore cannot be used for self- 
contained programs. 

If you use variables in this way, you can't call them 
directly by name after storing something there, because the 
create execution code will be overwritten. You'll always have 
to 'tick' their addresses on the stack. 

Second, the screen blanker has to be rewritten; we store 
the black pattern into the screen area directly instead of calling 
Quickdraw routines, which may not be used. This is a little 
slower (Quickdraw really deserves its name), making the 
blanking less 'instantaneous. Also, we may not use a 
DO...LOOP (reference to the kernel), so the blanking loop is 
implemented using BEGIN..UNTIL, a little more 
cumbersome, but still readable; and self-contained. See the 
definition of blankout in Listing 2. Note that HideCursor is 
not in the list of 'forbidden' traps. 

Third, we cannot intercept events from within the VBL 
task using EventAvail. This is the reason why in Bob Denny's 
example from V1#9 a GetNextEvent filter procedure was used. 
We'll have to do the same thing. 


The GNEFilter procedure 


A short review of the method to install a GetNextEvent 
hook: 


There is an (undocumented) system global at $29A which 
contains a location that GetNextEvent jumps to right after 
removing an Event from the queue. Through this hook, one 
can install a routine that will be called whenever 
GetNextEvent receives an event. A pointer to the event record 
is contained in A1. At the end of this routine, of course, one 
will have to jump to the location that was contained in $29A. 

The GNE hook routine that we are going to install will, 
each time a non-null event is received, update the last.action 
counter with the current number of system ticks and repaint 
the screen if it was blank. In order to keep the definition short, 
we call traps directly instead of going through the Machl 
‘glue’ mechanism. 

The GNEintfc routine saves most of the registers and 
restores them after exiting. A local stack (100 bytes) is set up 
for the Mach1 A6 stack pointer. Some inline assembly code is 
used to move arguments between the A7 and A6 stacks, and to 
setup a jump vector at the end of the routine. 


The vertical blanking task 


one.run is the heart of the vertical blanking task that will 
be the other part of the CRT saver. It checks whether one 
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minute has passed since the last non-null event and blanks the 
screen in that case. Furthermore, it then sets a global flag, 
dark, to indicate to GNEintfc that the screen is dark. At the end 
of each run, screen blanked or not, the task reschedules itself 
by resetting the counter in its VBL queue element. Registers 
are saved and restored, and the routine also uses the local stack. 
(Note: writing this I realize that in the case that the 
GetNextEvent filter is interrupted by the vertical blanking and 
one.run is run during that same interrupt, it will use the same 
local stack. This might create a problem; so far the CRT saver 
has not crashed on me. You might think of duplicating the 
stack area so that the two routines use independent stacks.) 


Installation of the CRT saver in the system heap 


Of course, the code that we defined so far is local to the 
Mach] system and will disappear as soon as Machl is exited. 
If we happened to install the CRT saver before, too bad! Most 
certainly the system won't survive this kind of abuse. 
Therefore it remains to copy the routines to a safe place in 
memory; well move them to the system heap before 
installing. The code that we have to copy is marked by the 
two headers START and END. The word install.blanker gets a 
pointer to a chunk of system heap (END - START) bytes long 
and copies the code to it. The offset is placed into the variable 
(yes, here we may use a good old variable) blockoffset. All 
references to the copied routines during installation (for 
initialization of flags and counters, and for the address passed 
to the VBL queue element) are made through the original 
addresses offset by this value. 

After the installation — (install.blanker and 
install. GNEfilter), you may leave Machl, wait one minute and 
See your screen go dark. Any keypress or mouseclick will 
make reappear whatever was there. 


Turnkeying the CRT saver Installer 


The word CRTsaver installs the tasks and quits Machl. 
This word is used for turnkeying the program: 


turnkey CRTsaver CRT 


will create an application file CRT, 19K long (Machl 
runtime overhead of 16K) which installs the CRT saver. 


Listing 1: CRT saver background task to run In the Mach1 
system 


( CRT saver task, € 1986 JL for MacTutor) 
only forth def initions 
also assembler also mac 


hex 
904 constant currentA5 
9EE constant grayRgn 
16A constant Ticks 
74 constant screenbits 
18 constant portrect 


decimal 
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( first define port structure ) 
header screenport 
. 2 allot € device ) 
14 allot € bitmap ) 
8 allot C portrect ) 
84 allot C remaining bytes ) 


C *** now define background task that does the blanking *** ) 


variable last.action 
variable max.ticks 
3600 max.ticks ! € 1 minute in ticks ) 
header myevents 

2 allot ( code ) 

4 allot ( message ) 

4 allot C when ) 

4 allot C where ) 

2 allot € modifiers ) 


: relevant.action 
138 € disk + key + mouse ) 
['] myevents call EventAvail 


: redraw 
call drawmenubar 
call frontWindow 
greyRgn @ call paintBehind 
call showcursor 


: blankout 
call hidecursor 
('] screenport call openport 
('] screenport portrect + call paintrect 
BEGIN relevant.action UNTIL 
ticks @ last.action ! 
('] screenport call setport 
redraw 


: monitor .events 
activate 
BEGIN 
PAUSE 
relevant action 
IF ticks @ last.action ! THEN 
AGAIN 


a 


: do.blank 
activate 
BEGIN 
PAUSE 
ticks @ last.action @ - max.ticks @ > 
IF blankout THEN 
AGAIN 


) 
400 1000 background CRTsaver 
CRTsaver build 


400 1000 background eventmonitor 
eventmonitor build 


: Sever.steart 
ticks @ last.action ! 
eventmonitor monitor.events 
CRTsaver do.blank 


* 
a 


Listing 2: CRT saver, witten in Forth, 
installation into eysten heap and Mach 1 
independent execution 
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for 


( CRT saver tesk for installation into VBLTask queue, © 1986 


JL for MacTutor ) 
only forth definitions 
also assembler also mac 


hex 
29A constant JGNEFilter 
824 constant screenbase 
904 constant currentA5 
9EE constant grayRgn 

16A constant Ticks 

14 constant screenbits 

19 constent portrect 
FFFFFFFF constant minusone 


.TRAP = _drawmenubar $A937 
TRAP = _frontwindow $A924 
.TRAP — _paintbehind $4900 
.TRAP = _newptr, sys $A51E 
.TRAP — -showcursor $4853 


CODE save.regs 

MOVE.W SR,-CAT7) 

MOVEM.L A1-A6/D8-D7,-CA7) 

RTS 
END-CODE MACH 
CODE restore.regs 


MOVEM.L (A7)*,A1-A6/00-D7 
MOVE.W CA7)+,SR 


RTS 
END-CODE MACH 
CODE getA1 
MOVE.L Ai,-CA6) 
RTS 
END-CODE MACH 
decimal 


header START 
( *** we need a local stack after the relocation *** ) 
header local.stack 100 allot 


CODE setup. local .stack 
TA -8CPC2,A6 C stack grows downward from here ) 
END-CODE 


( *** define port structure + some global variables *** ) 


header screenport 
2 allot € device ) 
14 allot ( bitmap ) 
8 allot C portrect 2 
84 allot ( remaining bytes ) 


header myevents 
2 allot € code ) 
4 allot ( message ) 
4 allot C when ) 
4 allot C where ) 
2 allot C modifiers ) 


( *** VBL queue element to be installed *** ) 


header VBLqelem 
4 allot C qLink ) 
2 allot € qType ) 
4 allot € vblAddr ) 
2 allot € vblCount ) 
2 allot C vblPhese ) 
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1 constant vType ['] dark @ g= 


4 constant aType : AND 
6 constent vblAddr IF blankout THEN 
18 constant vb1Count | 68 ['] VBLgelem vblCount + w! ( reschedule ) 
12 constant vblPhase restore.regs 
d 
( *** GetNextEvent filter proc definitions *** ) 
header END 
header SavedJGNEFilter 4 allot 
header dark 4 allot 
header last.action 4 allot ( *** install CRT blanker task 'one.run' into VBL queue *** ) 
header mex.ticks 4 allot 
3600 ' max.ticks ! € 1 min in ticks ) variable blockoffset 
: get.sys.block 
: CNEIntfc ['] end ['] start - 
save .regs MOVE.L (A6)*,D0 
setup. local.stack -newpir,sys ( get memory block in system heap ) 
MOVE.L A®,-CA6) 
getA1 wê ( event received? ) f 
IF ticks @ ['] last.action ! 
['] dark @ : install.blanker  ( | pointer offset -- } 
IF get.sys.block -> pointer 
Ø ['] dark ! | pointer IF 
-drawmenubar 9 ['] dark ! 
CLR.L -(AT) ticks @ ['] last.action ! 
-frontwindow pointer ['] start - -» offset 
grayrgn e offset blockoffset ! 
MOVE.L (A6)+,-CA7) ['] start pointer ['] end ['] start - cmove 
_paintbehind ( now make all the moves on the relocated block ) 
-Showcursor ['] VBLqelem offset * 
THEN dup qtype * vtype swap w! 
THEN dup vblAddr + ['] one.run offset + swap ! 
dup vblCount + 60 swap w! 
['] SevedJGNEF ilter e dup vblPhase + 5 swap w! 
MOVE.L (A62*,A8 call Vinstall drop 
restore.regs ELSE ." Not enough system heap for installation." cr 
JMP CAD) THEN 


: install.GNEf ilter 
( *** definitions for VBLtask that does the blanking *** ) JGNEF ilter @ ['] SavedJGNEFilter blockoffset @ + ! 
['] GNEIntfc blockoffset @ + JGNEFilter ! 


: blankout F 
call hidecursor 
screenbase @ 21888 + : remove .blanker 
screenbase @ ('] VBLgelem blockoffset @ + call Vremove drop 
BEGIN ; 
minusone over ! 
4 * 2dup « : remove.GNEf ilter 
UNTIL 2drop ['] SavedJGNEFilter blockoffset 6 + UGNEFilter ! 
1 ['] dark ! ^ 
4 
: CRTsaver 
: one.run install.blanker 
save .regs install.GNEf ilter 
setup.1local.stack bye 
ticks @ ['] last.action 8 - ['] max.ticks @ > A 
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Threaded Code 


A Custom Floating Point Package 


"12 Kflops - Forth goes InSANE" 


You might have noticed my frequent complaints about the 
slowness of the Apple 80-bit SANE routines and the non- 
availability of a reasonably fast 32 bit floating point package 
in Forth systems (and most other programming languages, for 
that matter, Fortran being the only exception). 


The scaling that is necessary if you want to do rapid 
calculations in Forth (using integer arithmetic) is a nuisance, 
and it is almost impossible to implement general purpose 
mathematical routines without floating point. Since I needed 
to run this machine as fast as possible, I set out to write a set 
of single precision real arithmetic routines. 


IEEE 32-bit real numbers 


The number format that we are dealing with is the IEEE 
standard and defined as follows: 


bit 31 (highest bit): sign (0 = positive) 
bits 30...23 : exponent (offset = 127) 
bits 22...0 : fraction part (23 bits with the 24th bit always =1) 


That is, a real number has the form 
(+/-)1.xxx...xxx * 2YYY, 


where the exponent yyy is obtained by subtracting 127 from 
the stored exponent; only the fraction part of the mantissa is 
stored because the integer part is always 1 by definition 
(otherwise, the fraction part will have to be shifted left and the 
exponent decreased until the integer part is =1; this is called 
normalization). 


The highest exponent, 255, is reserved for special cases: 
with zero mantissa it designates positive/negative infinity, and 
with non-zero mantissa it is a 'no-number' (Not a Number or 
NaN). This latter case is used to mark the results of undefined 
or illegal operations, such as 0/0, infinity - infinity, square 
root (-x), etc. The type of 'non- numberness' is indicated by 
the value of the mantissa. 


Floating point arithmetic is thouroughly treated in D. 
Knuth's 'The Art of Computer Programming’, Vol.2. Taking 
this excellent book as a guidance, the job to write the single 
precision routines becomes manageable. We'll first consider 
addition. 
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Floating point addition and subtraction 


To add two floating point numbers which have the same 
exponent is trivial, we simply add the fraction parts. 
Unfortunately, in real life numbers often have different 
exponents. Adding such two numbers is done by shifting the 
fraction part of the smaller one right by the difference in 
exponents. Then the fractions may be added; the exponent of 
the result is that of the larger of the two input numbers. 


This addition may generate a fraction overflow, when the 
new fraction part overflows into the 25th bit. In that case, the 
fraction has to be shifted right and the exponent increased by 
one. This might generate an exponent overflow; in which case 
we have to set the result to infinity. 


When adding two numbers of opposite sign, the fractions 
will have to be subtracted and the resultant fraction may be 
significantly smaller than 24 bit precision. We have to 
normalize the result, shifting the fraction left until the 24th 
bit is equal to one again, decreasing the exponent as we go. 
We assume that the input to our routines always consists of 
normalized floating point numbers; the routines will always 
return normalized results as well. 


Normalizing after subtraction may result in an exponent 
underflow. We could simply stop normalization and keep an 
unnormalized fraction part for very small numbers (in fact, the 
IEEE standard provides for this). I have chosen here to simply 
set the result equal to zero, since the algorithms become more 
complicated if one allows unnormalized small numbers. 


After normalization, the fraction part is rounded. This is 
necessary because we actually calculate the result with a higher 
precision than 24 bits; in general, we will have a 'raw' 32-bit 
result. The rounding algorithm implemented here goes as 
follows (bit O is the least significant bit of the 24 bit 
mantissa, bits (-1) and (-2) the bits below it): 


- if bit (-1) is equal to zero, don't change anything. 

- if bits (-1) and (-2) are equal to one, increment fraction by 
one. 

- if bit (-1) = 1, bit (-2) = 0, increment fraction if bit 0 = 1 
(round to next even number). 


Since rounding includes incrementing, we might generate a 


new fraction overflow, so we have to check for that again after 
rounding. 
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Getting the correct sign for the result is not too 
complicated, either; if both numbers have the same sign, the 
result will have that sign. If the numbers are of Opposite sign, 
the fractions have to be subtracted instead of added. If because 
of the subtraction the result fraction becomes negative, the 
fraction and the sign of the result have to be inverted. 


The result of the subtraction then is normalized and 
rounded as described before. 


The algorithm is implemented in Listing 1 in standard 
68000 assembly code of the Mach] variety. My code assumes 
that registers DO to D6 may be used freely, which is true for 
Mach1. If your Forth system (or any other system where you 
wish to implement this code) uses any of those registers, you 
will have to push them on the stack before you enter and pull 
them off again on exit. Or change register assignments. 


The Machl data stack is maintained by A6, so the 
operands are pulled off the A6 stack on entry and the sum 
pushed there on exit. This might also be a place where 
changes would be necessary going to a different system. 
Otherwise, you can take the code as it is. In MacForth, you 
will have to transfer it into reverse polish notation. NEON 
provides a standard assembler. 


Read through the listing and follow the algorithm in 
machine language; it is essentially the one described in Sec. 
4.2.1 of Vol.2 of Donald Knuth's set of books, except that 
normalization is only done after subtraction. 


There is some additional 'glue' which is specific to Machl. 
F>S and S>F move floating point numbers from the floating 
stack (D7) to the data stack (A6) and back, changing between 
80- and 32-bit precision. S- provides for subtraction: it simply 
changes the sign of the number on top of stack and then adds. 


««« BUG WARNING »»» 
- Palo Alto Shipping, please take note - 


As you see in the listing, I had to hand-assemble a BCHG 
#31,(A6) by doing a DC.L. This is because the Mach 1 
assembler still doesn't like some instructions. I would 
recommend to all of you using this (otherwise excellent) 
system to disassemble routines after assembly and quickly 
look whether there are differences. Another instruction with 
which I had problems is the ANDI.W and ANDI.B type (not 
the ANDI.L). Further down, in the code for multiplication and 
division, I had to move around those problems by hand-coding 
with DC.L. 


Multiplication 
The multiplication algorithm is somewhat simpler than 


that for addition. Its heart is a double precision multiplication 
of the fraction parts. A 24 by 24-bit multiply yields a 48-bit 
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result, only the upper 24 bits of which are needed (actually, 
some more for rounding - we'll have 32 bits as an intermediate 
result). 


Lets call the two operands u and v, their 8 most significant 
bits um and vq, the 16 least significant bits uy and vj. The 
result is then composed as follows (Fig.1): 


Um * Vm -> upper 16 bits of result; 

uj * vj -> lower 32 bits of (48-bit) result; 

Ug* v] + uj*vg -> 24 lower bits of the upper 32-bit part of 
result. 


The final 24-bit result is obtained by taking the upper 
rounded 24 bits of the 48-bit result. This result might be 
unnormalized by one position (the high bit might be =0); if 
that's the case, it will have to be shifted left by one and the 
exponent adjusted accordingly. After that adjustment, the result 
is rounded as shown above. 


The exponents are simply added in multiplication, after 
subtracting the excess (the offset of 127). At this point, over- 
and underflows are detected. The correct sign is automatically 
attached to the product by the following trick: 


result : 


24°24 bit multiplication of fracti 
Fig. 1 


—————————————————— 


on parts 


Before the two exponents are added, the signs are rotated 
into bit O of the registers so that the exponents are in the 
upper 8 bits of the word. After addition, bit O will be one only 
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when the operands had opposite signs. When the exponent is 
then rotated back, the sign bit will be set (=negative) only in 
that case. Of course, the low order bits have to be masked out 
before exponent and fraction are put back together again. 
Again, this algorithm is best understood by looking at the 
listing. 
Division 


Division is tough, since we can only divide 32 by 16 bits 
at a time, but we want a result that is precise to 24 bits! 
Ideally, we'd need a 48-bit register whose upper half we fill 
with the fraction part of the dividend, then do a 48-by 24 
division to get a 24 bit result. If we have less precision, 
things get much more complicated. Knuth is the answer again. 

Imagine we have two numbers u and v with upper and 
lower 16-bit halves um» Vm and uj, vj, which we want to 
divide. This can be written as 


Wm + 216w = (um + 2° ope, + 216v 
= (Um + 2 lén * 1/01 + 271 vg). 


Now is is convenient to know that the second term of the 
product in the second line may be approximated: 


1/(1 + 2716(vy vq) = 1 - 216(vy vm) . 
The way to go is now the following: 


- divide u (32-bit) by vq, getting a 16-bit quotient w'm 
and 16 bits of remainder. 

- Shift w'q, into the upper half of the result. Divide the 16 
bit remainder (shifted into the upper half of a 32-bit register) 
by Vm. This gives the 16-bit quotient wj. Combine w'm and 
W' to give w'. 

- compute w/v, (32bit/16 bit -> 16 bit). Multiply this 
result by vj to get a 32-bit product r', shift this product down 
by 16 bits to get r. 


- The result of the division is w = w' - r. 


The exponents have just to be subtracted in division, and 
correct sign is obtained by the same rotation 'trick' that was 
used in multiplication. Again, at this stage we have to watch 
for over- and underflows and do the correct rounding. Note that 
when adjusting the fraction parts to 32 bits at the beginning, 
the dividend is shifted one bit less than the divisor. This 
makes sure that the divisor is always larger than the dividend, 
otherwise another check for overflows would be necessary. No 
accuracy is sacrificed by this procedure. 


Testing the package 
accuracy and speed benchmarks 


The end of the listing contains some benchmarks that I 


wrote to check out the routines. The accuracy routines are used 
to check the precision of the package; with accuracy3 you will 
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see that the result deviates only in the lowest fraction bit from 
the 'exact' result obtained with the SANE routines. (I have not 
tested all cases, there may me some exceptional ones where 
the deviation is 2 bits.) 

The speed increase is considerable (Table 1): running the 
speed.test and fspeed.test for comparison, you'll find that you 
get a speed of 12,000 floating point additions per seconds 
(having subtracted loop overhead), and order-of-magnitude the 
same speed for the other operations. This is an increase by a 
factor of 5 to 10 over the SANE package. Just what we 
wanted. 

Another bug report (mine!) 


As I mentioned in my last article, there might have been a 
problem with the CRT saver the way it was written in that 
column. It turns out that the program actually can crash 
because of collision of the local stacks and therefore the two 
parts of the routine have to have separate local stacks. Listing 
2 shows the change that has to be made in the program. The 
MacTutor source disk contains the corrected version, which is 
to my knowledge safe to use (I'm using it now...). 

See you next time! 


Table 1: 
single and extended precision benchmarks 


10000 operations (pice) 


single add: 0.83 sec -> 12.0 Kflops - 
single sub: 1.0 sec -> 10.0 Kflops 
single mul: 0.95 sec -> 10.5 Kflops 
single div: 1.3 sec -» 7.7 Kflops 


extended add: 4.47 sec -» 2.2 Kflops 
extended sub: 4.73 sec -» 2.1 Kflops 
extended mul: 7.0 sec -» 1.4 Kflops 

extended div: 13.35 sec -» 0.75 Kflops 


speedup add: 5.36 
speedup sub: 4.8 
speedup mul: 7.37 
speedup div: 10.3 


Listing1:singleprecisionfloatingpointmathprimitives,for 
Installation Into Forth systems 


( 32 bit floating point routines ) 

( © 27.4.1986 J. Langowski /MacTutor ) 

( This code may be used freely for non-commercial 
purposes to speed up the inSANEly precise and slow 
Macintosh floating point package. Any inclusion in 
software that is distributed commercially requires the 
author's permission. ) 


only forth also assembler also sane 


CODE SF 
PEA (A6) 
SUBI.L #§A,D7 
ADDQ.L 8$4,A6 
MOVE.L DT7,-CAT) 
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MOVE.W %$100E,-CA7) ( reconstruct number from mantissa and exponent ) 
"8 Dd 


-Pack4 LSR.L } 
RTS BCLR 823,00 
END-CODE LSL.W 17,02 
SWAP.W D2 
CODE PS CLR.W D2 
MOVE.L D7,-CA7) OR.L D2,08 
ADDI.L #$A,07 @end MOVE.L D®,-CA6) 
SUBQ.L #$4,A6 RTS 
PEA (A6) 
MOVE.W #$1918,-CA7) @subtract 
-Pack4 SUB.L — D1,D0 
RTS BEQ @end 
END-CODE BCC @normal 
€ fraction v was larger than fraction u, change sign ) 
CODE S+ € 32 bit FP add ) BCHG #8,D2 
MOVE.L (A6)+,D1 NEG.L DØ ( make mantissa positive ) 
BEQ ei énorme! BMI @round | 
MOVE.L (A62*,D0 SUBQ.B #1,D2 
BNE @add.main BEQ @small ( expo underflow ) 
MOVE.L D1,-CA6) ADD.L DØ,DØ C faster then LSL.L 511,00 ) 
e1 RTS BRA @normal 
@small  MOVEQ.L *0,00 
@add.main BRA end 
MOVE.L DØ,D2 eovf1 MOVE.L *$7F800000,-CA6) 
( number in DØ will be called u ) ..R 
MOVE.L D1,D3 END-CODE 
C end in Div ) 
LSL.L %8,00 CODE S- ( 32 bit FP subtract ) 
LSL.L #8,D1 ( BCHG #$ iF, [A6] ) 
BSET #31,D9 DC.L $0856001F 
BSET #31,D1 S+ 
C now DØ and D1 contain the fraction parts, RTS 
Shifted into the upper part of the long word ) END-CODE 
SWAP.W D2 
SWAP.W D3 CODE S* ( 32 bit single precision multiply) 
LSR.W #7,D2 MOVE.L (A60*,D1 
LSR.W #7,D3 BEQ @makezero 
€ D2 and D3 contain exponent plus sign ) - MOVE.L (A62*,D0 
MOVE.B D2,D4 BEQ @end 
SUB.B D3,D4 C D0,D1 will be used for lower 16 bits of mantissa. 
( D4 contains the difference in exponent ) D2,D3 for exponent ) 
BEQ @expo . same MOVE.L D0,D2 
BHI @check . expo MOVE.L D1,D3 
( if v-exponent > u-exponent, exchange u and v ) SWAP.W D2 
NEG.B 04 SWAP.W D3 
EXG 08,01 C get rid of junk in 04,05 ) 
EXG D2,D3 CLR.W D4 
@check . expo CLR.W D5 
CMPI.B 125,04 ( move most significent 7 mantissa bits to D4,D5 
( if difference in exponents » precision, just return u ) and set implied highest bit = 1 ) 
BHI @back together MOVE.B D2,D4 
LSR.L D4,D1 C shift smaller fraction ) MOVE.B D3,D5 
ĉ@expo . same BSET #87,D4 
EOR.W D2,D3 ( test if signs are equal ) BSET 87,05 
BTST 88 D3 ( isolete exponent * sign in D2,D3 ) 
BNE @subtract ( if not, have to subtract ) ( ANDI.W *"$FF80,02 ) 
ADD.L  D1,D0 DC.L $0242FF80 
BCC @round ( ANDI.W "$FF80,03 ) 
( fraction overflow ) DC.L $0243FF80 
ROXR.L #1,D8 ( rotate sign into lowest bit D2,D3 ) 
ADDQ.B #1,D2 ROL.W 1,02 
BEQ Govf ROL.W #1,D3 
éround BIST #7 DO ( subtract exponent offset ) 
BEQ @back together SUBI.W *$7F99,D2 
BIST $6,D0 SUBI.W *$7F00,03 
BNE 6 incr ( sum exponents, check for over- or underflow ) 
BTST #8 DØ ADD.W 02,03 
BEQ @back together BVS eovf Ichk 


on 


@incr ADDI.L **$80,00 now do 24*24 bit multiplication of mantissa ) 
E.W 


BCC @back together .N 04,02 Cu-hi -> D2 D 
€ rounding overflow ) MULU.W D1,D2 C u-hi * v-lo -> D2 ) 

ROXR.L 1,00 MULU.W D8,D1 C u-lo * v-lo -> D1 ) 

ADDQ.B #1,D2 MULU.W D5,DØ C u-lo * v-hi -> DØ ) 

BEQ 6ovf 1 MULU.W 04,05 (€ u-hi * v-hi -> D5 ) 
6backtogether ADD.L 02,08 C u-hi*v-lo + u-lo$v-hi -> DØ ) 
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MOVE .W 


D5,D1 


C u-hi*v-hi -> LSWID11, 
MSW unchanged , contains MSW of u-lo*v-lo ) 


SWAP .W 


( put LSW and MSW in correct order ) 
ADD.L 


D1,DÓ € put it all together ) 


C Richa mantissa bit might have changed to one ) 
BP 


L @nohibit 
ADDI.W %$188,D3 
BVC éround 
BRA @ovf Ichk 


@nohibit ADD.L — D9,DO C if hi bit =Ø, make it =1) BNE @hifrac 
éround BTST #7,DØ CLR.W D4 
BEQ 6blk.exp LSR.L  *1,D0 
BTST *6 DO BRA @expo 
BNE @incr @hifrac LSR.L %2,D0 
BTST #8 DO C subtract exponents ) 
BEQ 6blk.exp @expo ROL.W #21,D5 
@incr ADDI.L *$80,00 ROL.W #1,D6 
BCC 6blk.exp BSET "1,05 
ADDI.W $100,03 ( ANDI.B #1,D6 ) 
BVC 6blk.exp DC.L $0206000 1 
@ovf Ichk BPL @makezero SUBI.W #$7F90,D5 
MOVE.L %$7F800000,-CA6) SUBI.W $7F00,06 
RTS SUB.W D6,D5 
@makezero MOVEQ.L #8,D0 BVS @exp.ovf] 
BRA @end ADDI.W "$7E00,D5 
( readjust exponent ) ADD.W — D4,D5 
6blk.exp ADDI.W *$7F00,0D3 ROR.W #1,D5 
BLE @makezero ( ANDI.W *$FF80,05 ) 
ROR.W #21,D3 DC.L $0245FF80 
( ANDI.W "$FF80,D3 ) BCLR 1$17,00 
DC.L $0243FF80 SWAP.W D5 
LSR.L 8,09 CLR.W D5 
BCLR #23, DØ OR.L D5 , Dd 
SWAP.W D3 @end MOVE.L D9,-CA6D 
CLR.W D3 RTS 
OR.L D3, D8 @byzero MOVE.L (A6)+,DØ 
@end MOVE.L D9,-CA6) BNE eovf1 
RTS MOVE.L 5$7F800400,-CA6) 
END-CODE RTS 
eovf1 MOVE.L $7F800000,-CA6) 
CODE S/ ( 32 bit FP divide ) RTS 
MOVE.L €A62*,D1 Gexp.ovf! BPL @makezero 
BEQ @byzero ( divisor = 8) MOVE.L $7F800000,-CA6) 
MOVE.L (CA6)+,D8 RTS 
BEQ @end ( dividend = 9) @makezero MOVEQ.L *0,D0 
MOVE.L DØ,D3 BRA eend 
SWAP.W DØ END-CODE 
MOVE.W D@,D5 
MOVE.L D1,D6 € accuracy and benchmark tests) 
SWAP.W D6 decimal 
( exponents in D5,D6 ) fp 9 float 
MOVE . W 5$100, D4 C exponent adjust ) : s. Sf f. ; 
( isolate mantissa in 03, D1 and shift up ) 
ANDI.L "$90TFFFFF, D3 1.8 f>s constant one 
ANDI.L ®§$@O7FFFFF,D1 19. fòs constant ten 
BSET  *%$17,D3 pi f^s constant pi.s 
BSET #$17,D1 2.718281828 fòs constant eu 
LSL.L #7,D3 1.8 fconstant fone 
LSL.L — 88,01 10. fconstant ften 
( divide 32 by 32 bits ) 
MOVE.L D1,D2 : accuracy 
SWAP.W D2 ( v-hi D one dup 
DIVU.W D2,D3 € [u/v-hil-hi) 20 Ø do 
MOVE.L D3, D ten s/ 2dup s* 
CLR .W DØ ( remainder ) s. cr 
DIVU.W D2,D8 € [u/v-hi]-10) loop 
SWAP .W D3. drop drop 
MOVE.W 08,03 ; 
MOVE.L D3,D9 C u/v-hi = w) 
DIVU.W D2,D3 € w/v-hi ) : accuracy2 
MULU.W D3,D1 C w*v-1lo/v-hi) one dup 
CLR.W DI 20 Ø do 
SWAP.W D1 C lo 16 bits ) ten dup s. s* 2dup s. s. 
SUB.L 01,08 € final 32 bit result ) S. cr 
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LSR.L 6,08 C adjust ) 
( round result, as before) 

BIST #1,D9 

BEQ @rounded 

BIST "0 DO 

BNE @incr 

BIST 12 D0 

BEQ @rounded 
@incr ADDQ.L #4,D8 
Grounded BIST #25 D9 


( account for zero hi order bit ) 
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loop timer fdrop fdrop ; 

drop drop : fmark5 pi 2.71828 1828 
counter 10000 Ø do fover fover f/ fdrop loop 
timer fdrop fdrop ; 


: @ccuracy3 
one fone : fspeed.test cr 
1000 Ø do fmark1! cr 
dup f dup fmark2 cr 
i. fmark3 cr 
i bf ften f/ fdup fos fmark4 cr 
f/ s/ dup u. dup S. fòs dup u. dup s. fmark5 cr 
S) f sof f- f. ) 
cr 
loop Listing 2: Correction of CRT saver routine, MT 
; V286 
€ This code has to be inserted after the START header. 
: bmark 1 References to setup.local.stack in the two routines have 
counter 10000 0 do pi.s eu drop drop loop timer ; to be changed to setup.GNE.stack and setup. VBL.stack, 
: bmark2 respectively ) 
counter 10000 Ø do pi.s eu st drop loop timer ; 
: bmark3 decimal 
counter 10000 Ø do pi.s eu s- drop loop timer ; 
: bmark4 header START 
counter 10000 Ø do pi.s eu s* drop loop timer ; 
: bmark5 ( *** we need two local stacks after the relocation *** ) 
counter 10000 Ø do pi.s eu s/ drop loop timer ; 
: Speed.test cr header GNE.stack 100 allot 
bmark1 cr 
bmark2 cr CODE setup.GNE.stack 
bmark3 cr LEA -BCPC2,46 
bmark4 cr ( GNE stack grows downward from here ) 
bmark5 cr RTS 
END-CODE 
: fmark1 pi 2.718281828 header VBL.stack 100 allot 
counter 10000 Ø do fover fover fdrop fdrop loop 
timer fdrop fdrop ; CODE setup.VBL .stack 
: fmark2 pi 2.718281828 LEA -8CPC2,A6 
counter 10000 0 do fover fover f* fdrop loop ( VBL stack grows downward from here ) 
timer fdrop fdrop ; RTS 
: fmark3 pi 2.718281828 END-CODE 


counter 10000 Ø do fover fover f- fdrop loop 
timer fdrop fdrop ; 
: fmark4 pi 2.71828 1828 
counter 10000 Ø do fover fover f* fdrop loop 
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Threaded Code 
Floating Point Package, Part II 


"Fast exp(x) and In(x) in single precision" 


We will continue with numerics this time, in order to 
give some examples how to put the 32 bit floating point 
package to practical use, and also because we got feedback that 
some more information about number crunching would be 
appreciated. 

First, however, it is time for some apologies: the bugs 
have been creeping into the multiply routine, and when I 
noticed the last few traces they left, the article was already in 
press. The problem was that when the number on top of stack 
was zero, the routine would all of a sudden leave two numbers 
on the stack, one of which was garbage. This problem has 
been fixed in the revision, which is printed in Listing 1. I 
hope there will be no more errors, but please let me know if 
you find any. A reliable 32 bit package is so important for 
numerical applications on the Mac! 

For many applications, the four basic operations +-*/ by 
themselves already help a lot in speeding up. However, alone 
they do not make a functional floating point package. For 
operations that are not used so frequently, like conversion 
between integer, single and extended or input/output on can 
still rely on the built-in SANE routines. But for the standard 
mathemetical functions you would want to have your own 
definitions that make full use of the speed of the 32 bit 
routines. 

Developing a complete package of mathematical 
functions would be a project that is outside the scope of this 
column. I'll only give you two examples that serve to show 
that a very reasonable speed can be attained in Forth (here, 
Mach1) without making too much use of assembly language. 
The two examples, In(x) and exp(x) are based on 
approximations taken from the Handbook of Mathematical 
Functions by M. Abramowitz and I.A. Stegun, Dover 
Publications, New York 1970. Furthermore, the routines 
given here profited a lot from ideas published in the April '86 
issue of BYTE on number crunching. 

First, we have to realize that a transcendental function 
like In(x), using a finite number of calculation steps, can only 
be approximated over a certain range of input numbers to a 
certain maximum accuracy. It is intuitively clear that the wider 
the range of the argument x, the lengthier the calculation gets 
to achieve the desired accuracy. Therefore, approximation 
formulas for standard functions are usually given over a very 
restricted range of x. We have to see that we play some tricks 
on the input value x so that we can get a reliable 
approximation over the whole range of allowed floating point 
numbers, which is approximately 10:38 to 10*38 for the 
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The handbook mentioned gives various approximations 
for In(x) with different degrees of accuracy. The accuracy that 
we need for a 24 bit mantissa is 2722 = 1077, and a suitable 
approximation for this accuracy would be 


Xx) = ax + ax” + a3x? + agx‘ + a5x>+ agx + 
a7x? * agx? + (error), [1] 


where for 0 ^ x ^ 1 the error is less than 3-108. The 
coefficients a} to ag are: 

ay = 0.9999964239, a) = -0.4998741238, 

a3 = 0.3317990258, a4 = -0.2407338084, 

as = 0.1676540711, ag = -0.0953293897, 

a7 = 0.0360884937, ag = -0.0064535442.. 


To calculate eqn. [1] more rapidly, it is of course 
convenient to write it as 


In(1+x) = x(a] + x-(ag + x'(a3 + x'(a4 + x'(as + x'(ag* 
x-(a7 + x-ag)))))) [2] 


where by consecutive addition of coefficients and 
multiplication by the argument the polynomial may be 
evaluated with a minimum of operations. In.base in Listing 
2 calculates eqn. [2] and gives a good approximation for In(x) 
in the range of x=1...2. 


For numbers outside this range, we have to realize that 
In(a:x) = In(a)  In(x), 

and in the special case when a = 2, 
In(2^ -x) = n-In(2) + In(x). 


Now, all our floating point numbers are already split up 
in such a way; they contain a binary exponent n and a 
mantissa x such that x is between 1 and 2. So it remains to 
separate the exponent and mantissa, calculate eqn.[2] for the 
mantissa and add n times In(2), which is a constant that we 
can calculate and store beforehand. 

The separation of exponent and mantissa is done in 
get.exp, which will leave the biased exponent on top of 
stack, followed by the mantissa in the format of a 32-bit 
floating point number between 1 and 2. We now have to 
multiply the exponent by In(2), an (integer) times (real) 
multiplication. Instead of writing another routine do do this, 
we use a faster method that, however, is a little memory 
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consuming: we build a lookup table for all values of n-In(2) 
with n between -127 and +128, the allowed range of 
exponents. Since the exponent is biased by +127, we can use 
it directly to index the table. The table consumes 1K of 
memory, so I wouldn't use it on a 48K CP/M system, but 
with 0.5 to 1 megabyte on a Mac, this can be justified. The 
lookup table is created using the SANE routines; this takes a 
couple of seconds, but it is done only for the initialization. 

For faster indexing, I also defined the word 4* in 
assembly, which does not exist in Machl (it does, of course, 
in MacForth). 

The final definition In first separates exponent and 
mantissa and then computes In(x) from those separate parts. 
Note that In as well as In.base are written completely in 
Forth. Fine-tuning of those routines, using assembler, should 
speed them up by another factor of 1.5 to 2 (wild guess). Still, 
you already gain a factor of 12 over the SANE routine (use 
speed.test to verify). The accuracy is reasonably good; the 
value calculated here differs from the 'exact' extended precision 
value by approximately 1 part in 107 to 108, just about the 
intrinsic precision of 32-bit floating point. 

Let's now proceed to the inverse of the logarithm, the 
exponential. The handbook gives us the approximation 


eX = ajx + anx? + a3x3 + a4x^ + a5x9+ agx + a7x? 
* (error), 


with the coefficients 


aj = -0.9999999995, a» = 0.4999999206, 
a3 = -0.1666653019, a4 = 0.0416573745, 
as = -0.0083013598, ac = 0.0013298820, 
a7 = -0.0001413161 . 


This approximation is valid to within 2-10-19 for x 
between 0 and In(2) = 0.6, and we use it for x = 0...1 for our 
purposes here, which still is sufficiently precise for a 24 bit 
mantissa. 

Again, we have to scale down the input value of x in 
order to get it into the range of validity of the approximation. 
This time, we use the relationship 


where N is the integer and f the fractional part of x. eN 
will be looked up in a table and ef calculated from the 
approximation. To get N, we need a real-to-integer conversion 
routine; this routine, together with its integer-to-real 
counterpart, is coded in assembler with some Forth code to get 
the signs correct (words s>i and i»s). The fractional part is 
calculated by subtracting the integer part from the input 
number; this is done in Forth without giving up too much in 
speed. exp puts it all together and calculates eX for the whole 
possible range of x values. 

As before, the lookup table for the eN values is 
initialized separately, using the SANE routines. 

The benchmark, speed.test, shows a 24 fold speed 
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increase of this exponential function as compared to the 80-bit 
SANE version. 

Other mathematical standard functions can be defined in a 
way very similar to the examples that I gave here. A good 
source of some approximations is the handbook mentioned 
above, also, many interesting ideas regarding numerical 
approximations can be found in BYTE 4/86. 


Feedback dept. 


Let's turn to some comments that I received through 
electronic mail on Bitnet and BIX. 

Here comes a comment (through BIX) on the IC! bug in 
NEON, which leads to a very interesting observation regarding 
the 68000 instruction set: 


Memo #82583 

From: microprose 

Date: Fri, 23 May 86 21:44:08 EDT 
To: jlangowski 

Cc: mactutor 

Message-Id: <memo.82583> 
Subject: "IC!" bug -- why it happens 


Just got my April '86 MacTutor, and I thought I'd answer 
your question about the bug in the "IC!" word. Register A7 
in the 68000 is always used as the stack pointer, and as such 
must always be kept word-aligned. As a special case, the pre- 
decrement and post-increment addressing modes, when used 
with a byte-sized operand, automatically push or pop an extra 
padding byte to keep the stack word-aligned. In the case of 
MOVE.B (A7)+,<dest>, this causes the most-significant byte 
of the word at the top of the stack to be transferred; then the 
Stack pointer is adjusted by 2 (not 1). I would guess that a 
similar thing is happening with ADDQ #3,A7; since you 
mention nothing about a stack underflow, it seems that this 
instruction is adding 2 to A7, not 4 as I would have suspected. 
(Otherwise, in combination with the following instruction, an 
extra word is being removed from the stack.) Since the desired 
byte is at the bottom of the longword, your solution is the 
best one (assuming that DO is a scratch register). 

I should point out that this is based only on the material 
printed in your column, as I do not own Neon. I do, however, 
have Mach 1 (V1.2), and I am looking forward to more 
coverage of it in future issues of MacTutor. 

Russell Finn 

MicroProse Software 

[Thank you for that observation. In fact, I tried to single 
step - with Macsbug - through code that looked like the 
following: 


NOP 

NOP 

MOVE.L A7,DO 
»»»»» ADDQ.L #3,A7 

MOVE.L DO,A7 

etc. etc. 


««««« 
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I didn't even get a chance to look at the registers! As soon 
as the program hits the ADDQ.L instruction, the screen goes 
dark, bing! reset! Also, running right through that piece of 
code (setting a breakpoint after the point where A7 was 
restored) resulted in the same crash. Therefore, this behavior 
should have nothing to do with A7 being used intermediately 
by Macsbug. I see two explanations: Either an interrupt 
occuring while A7 is set to a wrong value or a peculiarity of 
the 68000, which makes the machine go reset when this 
instruction is encountered (???). At any rate, the designers of 
NEON never seem to have tested their IC! definition, 
otherwise they would have noticed it] 

A last comment: we have received a nicely laid out 
newsletter of the MacForth User's group, which can be 
contacted at 

MFUG, 

3081 Westville Station, New Haven, CT 06515. 


With the variety of threaded code systems for the 
Macintosh around and being actively used, I think it is a good 
idea to keep the topics dealt with in this column as general as 
possible; even though I am using Mach1 for my work at the 
moment, most of the things apply to other Forths as well. 

What would help us a great deal, of course, is feedback 
from you readers ‘out there’. If you have pieces of information, 
notes or even whole articles on Forth aspects that you think 
would be of interest to others (and if it interested you, it will 
interest others), please, send them in. 


Listing 1: 32 bit FP multiply, first revision 
(and hopefully the last one) 


OR.L — D3,D0 

eend MOVE.L D0,-(A6) 
RTS 

END-CODE 


Listing2:Example definitionsfor exponential 
and natural logaritha, Machi 


only forth definitions also assembler also sane 
include" add.sub" 

include" mul.sp" 

include" div.sp" 

( files I keep my floating point routines ) 


CODE 4 
MOVE.L (A6)*,DÓ 
ASL.L 52,00 
MOVE.L D@,-CA6) 
RTS 

END-CODE MACH 


C extract biased exponent & mantissa 
from 32 bit FP 8 ) 


CODE get.exp 
MOVE.L (A62*,D0 
MOVE.L D0,01 
SWAP.W DØ 
LSR.W — *7,D0 
ANDI.L #8$FF,DØ 
MOVE.L D@,-CA6) 
ANDI.L *"$7FFFFF,D1 
ORI.L —*$3F800000,01 
MOVE.L D1,-CA6) 
RTS 

END-CODE 


CODE stoi 
MOVE.L CA6)+,DØ 

MOVE.L D0,D1 

SWAP.W DØ 

LSR.W  #7,DØ 

SUBI.B #127,D9 

BMI @zero 

BEQ Gone 

ANDI.L *$7FFFFF,D1 

BSET #23,D1 


CODE x 
MOVE.L (462*,D1 BPL @nohibit 
BEQ @zero ADDI.W #$100,D3 
MOVE.L (462*,D0 V @round 
BEQ @end BRA @ovf Ichk 
MOVE.L DØ,D2 @nohibit ADD.L — D2,D0 
MOVE.L D1,D3 @round BIST #7,D9 
SWAP.W D2 BEQ 6blk.exp 
SWAP.W D3 BIST #6 ,D9 
CLR.W D4 BNE @incr 
CLR.W D5 BIST  #8,DØ 
MOVE.B D2,D4 BEQ @b1k.exp 
MOVE.B D3,D5 eincr  ADDI.L *$80,00 
BSET #7,D4 BCC 6blk.exp 
BSET 87,05 ADDI.W 5$100,03 

C ANDI.W  "$FF80,02 ) BVC @blk.exp 
DC.L $0242FF80 @ovf Ichk BPL @makezero 

( ANDI.W *"$FF80,03 ) MOVE.L *$7F890080,-CA6) 
DC.L $0243FF80 RTS 
ROL.W #1,D2 @makezero CLR.L DØ 
ROL.W #1,D3 MOVE.L DØ,-CA6) 


SUBI.W #$7FØØ,D2 

SUBI.W *$7F00,03 

ADD.W D2,D3 

BVS @ovf Ichk 

MOVE.W D4,D2 

MULU.W D1,D2 
MULU.W DØ,DI 

MULU.W D5,DØ 

MULU.W D4,D5 

ADD.L 02,08 

MOVE.W D5,D1 

SWAP.W D1 

ADD.L 01,00 
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RTS 
@zero CLR.L DØ 
MOVE.L D@,CA6) 


RTS 

6blk.exp ADDI.W #$7FØØ,D3 
BLE @makezero 
ROR.W #1,D3 

( ANDI.W "*'$FF89,03 ) 
DC.L $0243FF80 
LSR.L — $88,D0 
BCLR %23,D0 
SWAP.W D3 
CLR.W  D3 


CMP.B %8,D8 
BCC elong.shift 
LSL.L  D0,01 
CLR.W Di 
SWAP.W DI 
LSR.L #7,D1 
MOVE.L D1,-CA6) 
RTS 

elong.shift 
LSL.L #7,D1 
SUBQ.B *7,D8 
CLR.L D2 

@shifts LSL.L #1,D1 
ROXL.L #1,D2 
SUBQ.B #1,D8 
BNE @shifts 
CLR.W Di 
SWAP.W DI 
LSR.L #87,D1 
LSL.L #88,D2 
ADD.L 02,02 
OR.L D2,D1 
MOVE.L D1,-CA6) 
RTS 

ezero CLR.L DØ 
MOVE.L D9,-CA6) 
RTS 
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Gone MOVEQ.L **1,D0 
MOVE.L D®,-CA6) 
RTS 

END-CODE 


: S)1 dup Ø< if stoi negate else stoi then : 


CODE itos 
MOVE.L CA6)+,D@ 
BEQ @zero 
CLR.L OD! 


MOVE.L "$7F,D2 
eshifts CMPI.L 31 DØ 
BEQ Gone 
LSR.L 1,08 
ROXR.L #1,D1 
ADDQ.L #1,D2 
BRA @shifts 
Gone LSR.L #8,D1 


LSR.L #1,D1 
SWAP.W D2 
LSL.L 87,02 
BCLR #31,D2 
OR.L 02,01 
MOVE.L D1,-CA6) 
RTS 

ézero MOVE.L D0,-(A6) 
RTS 

END-CODE 


hex 

: Ps dup Ø< if negate itos 80000000 or 
else itos then ; 

decimal 


: S. SOF f. ; 
vocabulary maths also maths definitions 


decimal 
fp 9 float 


-inf fòs constant -infinity 
inf f?s constent infinity 


1.0 fòs constant one 
10. fòs constant ten 
108. fòs constant hun 
pi f>s constant pi.s 
2.718281828 fòs constant eu 


( exponential, natural log ) 


.9999964239 fòs constant alln 
-.4998741238 fòs constant a2in 
.33 17999258 f>s constant a3in 
-.2407338084 f>s constant a4In 
. 1676549711 fòs constant a51n 
-.0953293897 fòs constant a6ln 
. 9368884937 fòs constant a7ln 
-.0064535442 fòs constant a8ln 


variable In2table 1020 vallot 
2.0 fn f>s constant 1n2 
: fill.1n2table 
256 Ø do 1n2 i 127 - bs s* 
i 4* In2table + ! 
loop 


s 
: In. base 
one s- a8]n over s* 

alin s+ over s* 
a6]ln st over s* 
aoln s+ over s* 
a4in s+ over s* 
a3ln st over s* 
&e2]n st over s* 
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alin s+ s* 
) 


: In dup Ø if get.exp 


In. base 
Swap 4* In2table + 6 
St 
else drop -infinity 
then 
: ]nacc 
1000 8 do 


i.i bs In dup s. 
i if fin fdup f. 
f f- f. cr 
loop 


variable exptable 728 vallot 
: fill.exptable 
176 Ø do i 87 - bf fe^*x fos 
i 4* exptable * ! 
loop 


) 


-.9999999995 fòs constant alexp 
4999999206 f>s constant a2exp 
-. 1666653019 f>s constant a3exp 
.8416573745 fòs constant a4exp 
-.0083013598 fòs constant abexp 
.0013298820 fòs constant a6exp 
-.8001413161 f?s constant a7exp 


: exp.base a7exp over s* 

abexp S+ over s* 
adexp s+ over s* 
a4exp st over s* 
asexp S+ over s* 
a2exp st over s* 
alexp s+ s* 

one st 

one swap s/ 


d 
: exp dup s?i swap over i?s s- exp.base swap 
dup -87 « if 2drop 0 
else dup 88 » if 2drop infinity 
else 87 + 4* exptable + @ 
( get exp of integer part ) s* then 
then 


expacc 
1000 Ø do 
i. i Ds hun s/ exp dup s. 
i Df 108. f/ ferx fdup f. 
S) f f- f. cr 
loop 


emptyloop Ø 1000 Ø do dup drop loop drop ; 
: femptyloop Ø. 1000 Ø do fdup fdrop loop fdrop ; 
: testexp ten one s+ 1000 Ø do dup exp drop loop 
drop ; 
: testfexp 11. 1000 Ø do fdup fe^x fdrop loop 
fdrop ; 
: testin ten one s+ 1000 Ø do dup In drop loop drop 
: testf In 11. 1000 Ø do fdup fin fdrop loop fdrop 
: Speed. test cr 
." Testing 32 bit routines..." cr 
: empty..." counter emptyloop timer cr 
exp..." counter testexp timer cr 
In..." counter testIn timer cr cr 
Testing SANE routines..." cr 
empty..." counter femptyloop timer cr 
" exp..." counter testfexp timer cr 
In..." counter testfin timer cr 
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Threaded Code 


Adding Record Structures to Forth 


Records with local field names 

Data representation is a field that is neglected by many 
Forth dialects. Basic Forth-83 doesn't even provide for simple 
one and two dimensional matrices, neither are more complex 
types of data supported, such as Pascal records or C structs. 
These latter forms of data representation play a most important 
role in Toolbox programming, since very many traps expect 
pointers to records as parameters. 

A letter received through BITNET from a reader who was 
wondering how to install a way to handle such data structures 
in Forth got me started on this month's column: 

"I posted the following article to the USENET, but got 
little in the way of a response. Any help you can give will be 
much appreciated. By the way, I know that the rectangle 
definitions given below are inaccurate for the Mac, but I was 
trying to be machine independent in posting to the Forth 
language newsgroup. 

From postnews Thu Jun 12 15:23:34 1986 

Subject: Defining a structure in FORTH? 

Newsgroups: net.lang.forth 

Distribution: net 

I am very much a novice FORTH programmer, and I don't 
even have a good textbook to go by. I recently purchased a 
FORTH for my Macintosh at home (MACHI, distributed by 
the Palo Alto Shipping Co.), and would like some advice. 
Professionally I do a lot of work with LISP, and I would like 
to implement something similar to a " DEFSTRUCT' package 
in FORTH. In other words, I'd like to be able to do 
something like: 

DEFSTRUCTE RECTANGLE 

TOP 2 
LEFT 2 


BOTTOM 2 
RIGHT 2 JENDSTRUCT 


Which would automatically define the following: 
8 CONSTANT RECTANGLE-SIZE 
: RECTANGLE-TOP@ (8- n2 @ ; 
: RECTANGLE-TOP! Cna- )! ; 


: RECTANGLE-LEFT@ C a-n)2+6; 
: RECTANGLE-LEFT! (n8-22 * ! ; 
: RECTANGLE-BOTTOM@ (8- n24* 8; 


: RECTANGLE-BOTTOM! Cna-)4+! ; 
: RECTANGLE-RIGHTe (8-n26*€; 
: RECTANGLE-RIGHT! (n8- 26 * ! ; 
: MAKE-RECTANGLE ( whatever code 

necessary to allocate 8 bytes of variable storage and 
assign a dictionary entry to the word which follows.This I 
guess would be implementation specific. ) ; 

While I'm sure that this could be done by defining 
DEFSTRUCT[ so that it constructs all of the necessary 
dictionary headers etc. at the bit and byte level, this would 
doubtless be complicated and not very portable. I wonder 


then, if there is a higher level method of defining such a beast? 
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Jorg Langowski 

EMBL, clo I.L.L. 
Grenoble, Cedex, France 
MacTutor Editorial Board 
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MACH 2 


Any help (even "no that can't be done") would be appreciated." 

—Bruce Florman florman@rand-unix.ARPA 

Since I think the question put forward by Bruce Florman is 
of very general interest to Macintosh Forth programmers, I'll 
try to show a way how such data structures may be 
implemented in MacForth or Mach2. 

Structures in MacForth (CSI method) 

MacForth (Kernel 2.4) provides a simple and effective way 
to implement structure definitions. A structure definition is 
a way to assemble information about a data structure (the 
lengths of the various fields and the total length of the 


structure). Example: 
structure testrec 


long: “date 
long: “time 
byte: “flag 
28 . string: “description 
Structure. end 


defines the data structure testrec with four fields, date, 
time, flag, and description. testrec is not a defining 
word. When executed, it merely leaves on the stack the length 
of the structure that is going to be defined; this number can 
then be used to allot an appropriate number of bytes in the 
dictionary. So, creation of a testrec would be done like: 

create myrec testrec allot 

The words that are used to access the field, “date, time, 
^flag, and “description, simply add an offset to the number 
on top of stack. If this number is the address of a valid 
structure, like myrec, 

Byrec “flag 

would indeed yield the address of the flag field in myrec. 
[Note that the circumflex in front of the field names is purely 
a MacForth convention, you could name the fields as you 
like]. 

This solution is beautifully simple and helps very much 
improving the readability of your program text if you are 
working with lots of structured data types. There is one 
drawback, however, that the field name definitions are global 
to the program and therefore violate the conventional 
definition of a Pascal record, in which field names are always 
local to the structure. 

This means you have to exercise a lot of discipline when 
you work with structures defined in this way. On executing 
a field operator, it is not checked whether the address on top of 
stack is really the address of a structure, so bugs that leave 
unexpected values on the stack would be harder to detect. 
Furthermore, since all the field names are global, they may 
not occur in several different structure definitions in different 
contexts. 

Therefore, Id like to present an alternative to CSI's 
implementation of structures which uses local field names. 
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This is slower during compilation, since every structure 
definition will have its own local dictionary that has to be 
searched, but in most cases has the same speed during 
execution. It offers the additional advantage that by a very 
simple modification, a rudimentary NEON-like class 
behavior may be built in. 

Record definition with local fleld names 

From now on, we'll call the type of data structure dealt 
with a record, to emphasize the similarity with Pascal 
records. A record definition will be a template from which an 
arbitrary number of instances of this record can be built (note 
that this already strongly resembles NEON's terminology). 
Each instance will consist of a reference to its template and the 
data fields as defined in the template (Fig. 1). 

A record definition (Listing 1) then consists of: 

- the word :record, which sets up a defining word for the 
instances and initializes the stack for the field name definitions 
following; 

- field name definitions (>long, >word, etc.), which add 
names to the record template and store (after the name) the 
length of the data field and its position within the record: 

- s3record, which closes the definition, stores a 16-bit zero 
and the total length of the record at the end of the template, 
and checks for completeness of the definition. 

An example definition is given at the end of Listing 1. 

Run-time behavior of records 

The run-time behavior of a record template defined through 
:record is given by the word do.record. This word scans the 
list of field names in the record template and creates a new 
instance of the record with a pointer to the template in its first 
four bytes and space for the data fields following it. 

The run-time behavior of the record instance is just to 
place its base address (the pointer to the template) on the 
Stack. Access to the record fields is provided through ^field, 
which expects an address of a record instance and a string 
address on the stack. ^field will search the record template for 
the field name and leave the (absolute) field address on the 
stack or abort with an error message if the string does not 
match any field name in that particular record. 

The operator ^ is provided for readability; executing 

ri * date 

will give the same result as executing 

r1" date" “field. 

So far, we have only talked about execution time behavior 
of records. However, most of the times one would want to 
compile references to record fields into Forth definitions rather 
than execute them directly. For inclusion into Forth 
definitions, one way is to write 

: test! [ r1 * date J literal ....... ; 

which compiles the address of the date field of r1 into the 
definition as a literal. If a run-time reference to an arbitrary 


record is to be made, one can either write 
: test2 € record addr -- addr of date field ) 
* date” “field ; 


which also checks at runtime for the validity of the date 
reference (something like ‘late binding'), or, for faster 


execution, one writes 
: test3 (record addr -- addr of date field ) 
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pointer to template 
field 4 


field 6 


Fig.1 : record instance with Its template 


[ r1 dup ^ date - 1 literal + ; 

which assumes that the record address passed at run time 
refers to a record of the same type as r1. But in that case, 
CST's structure definition is, of course, equivalent and easier 
to read. 

From record to class definitions - using 
record fields as vectors 

A simple, again very rudimentary, implementation of a 
NEON class like structure can be obtained using the record 
definition given here. If the data contained in a >long field 
(lets say with the field name print) is the cfa of a Forth word, 
writing 

rl* print @ execute (Mach2) or 


ri ° print @ make. token execute 
(MacFor th) 


will execute the word that the print field of r1 points to. 
(In MacForth, one might also reserve a >word field and store 
a token there, then say r1 ^ print @ execute). 

Vectors within records are very similar to methods 
associated with objects. Of course, method inheritance from 
superclasses has not been implemented here, so the 
resemblance to 'real' object oriented languages is not very 
strong. 

Some extensions to Mach2 for MacForth 
compatibility 

At the beginning of Listing 1 I have included some 
definitions for MacForth words that are not included in Mach2. 
Those are the words =cells, needed, and String. The latter, 
a string comparison operator, has been implemented in two 
different ways; in both cases, the top two stack items are 
string addresses, and the flag returned is 0 if the strings are 
equal and 1 if not. =string uses the IUMagIDString routine 
from the intemational utilities package, which does a better 
job in comparing name strings that contain umlauts, 
diacritical marks etc., but is slower. -string uses the 


445 


_Cmpstring trap, which is much faster and the recommended 
one to use for applications like this one. 
MacForth Plus - no more Level 1,2,3 

Readers of the CSI newsletter might have received an 
announcement of their latest update to MacForth by the time 
this is in print. Anyway, I'll tell you a few things about it 
that I was told in a letter at the time I wrote this (June). 

e MacForth Plus, to be released at the end of August, will 
supersede all previous versions and levels of MacForth. Its 
version of the kernel will "...execute considerably faster than 
K2.4 It will execute faster than Mach1." 

e Normal text file editing will be supported, as well as 
block file editing. 

e Multitasking, which was undocumented, but in principle 
possible with MacForth, will be fully supported in MacForth 
Plus. 

e The documentation will contain in one single manual the 
Level 1,2 and 3 informations, as well as the new features. 

e Stand-alone applications can be produced by a built-in 
turnkey mechanism. 

* The upgrade from Level 2 will be available for 
(scheduled) $49 upgrade fee, which includes the manual. Level 
3 users will receive a free upgrade. 

This sounds very interesting. I hope I'll soon have a test 
copy to write about. 

Listing 1: record structures in Forth 
( Structures, Mach-2 version 


Adding a structure compiler to Forth. JL 26.6.86. 
This file defines a Pascal-like ‘record’ structure; 
a record is a template for instances of the structure. 
Example 
‘record a 
> long field! 
> word field2 
record 
myrec r1 \this creates an instance r1 of myrec whose fields 
may be accessed through myrec ^ fieldi etc.. 
for ‘late binding’ usage, the word “field is provided) 
only forth also assembler 
decimal 
C some MacForth definitions that Machi is missing ) 
: =cells dup 2 mod * ; 
: needed depth 1- > abort” NEEDED- not enough stack items” ; 


CODE sstring 
count rot count rot swap 
MOVE.W %8,-CAT) 
MOVE.L $C(A62,-CA7) 


MOVE.L $8(462,-CAT) 
MOVE . W $6CA6),-CA7) 
MOVE . W $2CA6),-CA7) 
MOVE . W #12,-CAT) 

: -packó 
ADDQ.L #8, A6 
ADDQ.L #8, A6 
MOVE .W CAT)+,-CA6) 
MOVE .W #9 ,-CA6) 
RTS 

END-CODE 


CODE -string 
count rot count swap 


MOVE.L  CA6)+, AD 
MOVE.L  CA6)+,D0 
SWAP.W DØ 
MOVE.L  CA6)+,D1 
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MOVE.W 01,00 
MOVE.L (A6)+,A1 
_cmpstr ing 
MOVE.L . D0,-(A6) 
RTS 

END-CODE 


€ do.record, creating one instance of a record ) € 962686 jl 
) 
: do.record € addr of master | -- ) 
create dup, 
begin dup cê dup while C not zero, i.e. end) 
l+ =cells 4 + + C next field in template ) 
repeat 
drop 2+ wê € length stored here ) allot 
does? € nothing special ) 


on 


‘record ;record and friends) ( 062686 jl 


:record create 13579 4 does? do.record ; 


record 2 needed 
Øw, C end of list) w, C total length ) 
13579 = Ø= abort" ;record without :record" 


: put.fieldname 
32 word here over cê 1* dup =cells allot cmove ; 


field defining words ) € 062686 jl 


A ml 


: ?Tong € addr | addr+4) 
put.fieldname dup w, 4w, 4 * ; 
: )word € addr | addr+2) 
put.fieldname dup w, 2 w, 2+ ; 
: )byte € addr | addr+1) 
put.fieldname dup w, 1w, I+ ; 
: bytes € addr V n | addr*n ) 
put.fieldname over w, dup w, + ; 


"field, addressing a field within a record )  ( 862686 j] 


ww oN 


: “field € addr name | address of field ) 
over @ ( addr name master ) 
begin 2dup -string while C no match ) 
dup c@ 6 + =cells + 
dup cê = ( end of list ) 
abort” RECORD- specified field does not exist" 
repeat 
C match found ) 
dup cê 1+ =cells + wê ( start within record ) 
swap drop + C address of field ) 


4 


(^) ( 062686 jl ) 


: * 82 word “field ; 


: example of a record structure ) ( 962686 jl 
:record testrec 
> long date 
»long time 
byte flag 
word counts 
38 »bytes description 
;record 


testrec r1 
testrec r2 PT 


ze 


et. 
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Forth Forum 
Keyboard Re-Mapper Utility 


Keyboard configuration and 
reconfiguration 

This time I'd like to address a problem 
that is rather neglected in Inside Macintosh, 
but not by MacTutor, and that is the 
configuration of the Mac keyboard. [As 
background, you may wish to refer to the 
August issue for an article by Joel West and 
David Smith on the Keyboard Sleuth.] The 
section on international resources mentions 
the different existing keyboards, their layouts 
and the keycodes; but it is nowhere said 
explicitly how the keycode that is sent out 
when a key is pressed is mapped to an ASCII 


character and where the tables are kept that are used for that 
assignment. 

There is one program, the Localizer, that is generally 
used to change the keyboard configuration from one layout to 
another. This works well for the standard keyboards that come 
for the different countries in which the Mac is sold. It would 
be very convenient, though, to be able to change the keyboard 
mapping according to one's taste. That way one could layout a 
Dvorak keyboard or make simple changes just to have some 
different symbols available, without changing the whole 
keyboard arrangement. As an example, I prefer to have a 
decimal point instead of a comma on my (German) Mac+ 
numeric keypad, without changing the rest of the layout so 
that all the symbols stay where they are. There is no 'canned' 
configuration in the localizer that provides for this change. 
So, here's a nice chance to write a small application in Forth 
that does something useful and at the same time show some 
instructive details about how the keyboard is configured. 

The INIT 0 and INIT 1 resources 

Doing so requires some NOS Ying around in the routines 
that translate keycodes into ASCII characters. These routines 
are built at system initialization time through the INIT 
resources ID=0 and ID=1. [One can find this out easily by 
looking at the Localizer, which contains quite a few INIT 
resources that all look very much the same except for some 
tables that contain the actual keyboard mapping]. Disassembly 
reveals how a keycode is translated into an ASCII character by 
the INIT routines. See Listing 1. The modifier bits (Shift, 
Option, Caps Lock) are taken as an index into a small offset 
table, from which the beginning of the actual translation table 
is obtained. The keycode then serves as an index into that 
table. Two different translation tables exist for the old Mac 
and the Mac+ keyboards. The keyboard type is read from the 
system global KybdType at $21E, which is continually being 
updated by the background routine that checks for the 
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Keyboard Configuration Editor 


: Macintosh Keyboard Remapper 
1^ 1986 J.Langowski / MacTutor 


: Closing the window will update the resource file. 


: Type the key you'd like to change - 
a f - Keycode = 3 , Modifiers = 0000, actual mapping - f 
] Do you want to remap this key (y/n?) - 


k 


Fig. 1 Our Keyboard Remapper In Mach2 


presence of a keyboard. A hex $B here means we have a Mac+ 
keyboard plugged in, other numbers so far refer to the old 
keyboard, and keypad, optionally. [A zero means, there is no 
keyboard... but in that case, we'll never get to this routine 
anyway...] 

A very simple way to change the translation table to our 
preferences is to emulate the table lookup process in Forth, 
starting with the keycode. Machl (also the new version 
Mach2) contains the word ?TERMINAL which returns the 
character code, keycode and modifier flags if a key has been 
pressed. 

Listing 2 defines a couple of words that will return the 
absolute address of the translation table entry from the keycode 
and modifiers. keycode and modifiers retum the respective 
fields. keyaddress, given a modifier / keycode input on the 
Stack, determines which INIT resource to use (INIT 0 for the 


31 16 15 8 7 0 


Modifier Flags Key Code | Char Code 


Format of the 32 bits returned by ?TERMINAL 


main keyboard and INIT 1 for the numeric keypad), leaves a 
handle to that resource on the stack and the table entry's address 
on top of it. This address can then be used by the remapping 
routine to put a new entry into the table. The handle will be 
used to call _ChangedResource to mark the INIT resource as 
changed so that it is rewritten when _UpdateResource is called 
at the end. 

get.keyl.data and ^ get.key2.data are words that are 
used by keyaddress to determine the beginning of the 
translation tables for the main and numeric keyboards. They 
are somewhat kludgy as they make use of the internal structure 
of the INIT 0 and INITI1 resource codes, reading the table 
addresses out of the LEA <data>,AO instructions at the 
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beginning of the code. When a system is released where those 
instructions occur in different positions, my program will get 
completely lost. In that case, it would either have to be 
modified to accommodate the new addresses or the kludge 
would have to be generalized, using a routine that looks for a 
LEA «data»,AO instruction. All this is embarassingly bad 
programming style, but it was the simplest way that I could 
think up to find the table addresses. 

The INIT resources are read once at the beginning of the 
main word remap and stored in two variables hand0 and 
hand1. remap itself is an endless loop which comprises the 
user dialog for remapping of the keys. When the user hits the 
go-away box, the loop is exited through a vector which is 
installed in the task's goaway-hook; the resource file is 
updated (file id=0 indicates the System file), and control is 
returned to the Finder. 

The program can be compiled into a standalone 
application through the normal turnkey process built into 
Machl1; a turnkeyed version can be found on the MacTutor 
source disk. 

While the remapper is being used, the INIT resources 
already in memory from boot-up will of course stay as they 
are. Only the copies of INIT O and INIT 1 in the present 
System file are changed and rewritten. This means that your 
keyboard will stay in its old configuration until you reboot 
with the disk that contains the changed System file. 

Mach2, assembler bug, etc. 

The new version of Mach - Mach2 - has been released a 
long time ago as you read this. As I write this, however, I 
have just taken a short look at the changes and improvements 
that have been made. The main change for execution speed is 
that the DO...LOOP index and limit have been moved from 
the loop stack into registers (only the innermost loop). This 
speeds up loop execution tremendously, so that the famous 
Sieve now executes in just about seven and one half seconds, 
which is only one second slower than TML Pascal code. 
Another benchmark I wrote that does 50 screen inversions 
(explicitly, without calling InvertRect) also executes only 
about 15% slower than Pascal code. 

The disadvantage is that many more registers are now 
being internally used by the Mach2 system. In fact, Palo Alto 
Shipping warned me not to use any registers in CODE 
definitions without saving and restoring them. Therefore, if 
you try to use the floating point routines or many of the other 
examples that you could find here with Mach2, you're likely 
to be disappointed. Inserting MOVEM.L A0-A4/DO-D7,-(A7) 
and MOVEM.L (A7)+, A0-A4/DO-D7 in strategic places will 
help tremendously to fight frustration in that case. 

The assembler bug which caused faulty coding of some 
instructions (see V2#8) has been fixed, and they even promised 
that the Forth debugger would work Real Soon Now. 
Meanwhile, TMON is still the best way to debug with 
Mach2. 

Where did the $%&§ output go... 

A multitasking system like Mach has its peculiarities, 
which have to be learned. Somebody from the local developer's 
group had problems getting Quickdraw calls drawing into a 
window he had set up in Mach1. When he would turnkey the 
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program, however, everything would work fine. It seemed like 
under some circumstances, with the Machl system window 
open, the system would use a different grafPort from what he 
thought. 

There is a rather simple explanation to this problem. 
Mach] keeps a flashing cursor going in any window in which 
QUIT, the interpreter main loop, is running, which causes 
the current port to be reset to that window's grafPort. It is the 
programmer's responsibility to make sure that the currently 
active grafPort is the one that one wants to use. Since any 
task keeps a pointer to its associated window in a user 
variable, this is easy to achieve by doing a  setPort to this 
window. (One could argue that the task scheduler should 
automatically reset the current port to the task's own window. 
In my opinion, that would not be a good idea, since it would 
create a lot of overhead on switching tasks. Furthermore, the 
task actually might want to use another grafPort, this would 
make the initial resetting unnecessary anyway.) 

Listing 1: excerpts from the INITO and INIT1 key 
translation routines 


alphanumeric keyboard translator, Apple System File 


INITS BRA com.1 ; setup jump vector 
proc2 BRA.S  lac.2 


data1 DC. W $FFFF ,$4845,$5943, 1,$301,0 
proc3 LEA datas, Ad ; Mact translate table 
CMPI.B 11,KybdType ; 11 = Mac* 
BEQ.S  lac.1 
LEA data9, Ad ; Old Mac translate table 
lac-1 MOVEQ — **7,00 
AND D1,08 


ADD D,DØ ; modifier byte*2 
MOVE  ØCAO,DØ.W),DØ ; offset for modifiers 


ADD D2,D0 

d 0CA0,D0.W),D0 ; table entry 

RT 
lac.2 CMPI 852,D2 ; main entry point, D2 contains 
keycode 

; lec-3 ; wes modifier key pressed? 

BSR proc3 ; if not, translate through table 

TST.B  KeyMap*6 

BPL.S  1lac.4 ; if no control key 


BTST 80,D1 ; shift pressed? 


BEQ.S  lec.4 
BTST #2,D1 ; option pressed? 
BNE.S  lec.4 


BCLR 80,D1 ; clear shift bit 
BSR proc3 ; end retranslate 
#48 D8 ; is it 

lac_4 ; a number key? 
#57,D8 


BMI.S  lec.4 
ScrÜmpEnb ; deal with FKEYs 
BEQ.S  lac.4 
#48 DO 
DØ ,ScrDmpType 
lac_3 %9 00 
lac_4 l 
.( code that deals with diacritical marks, 
etc. etc. ) 


MOVEQ 


: ; Mac+ key translate table (German keyboard) 
DC.W $10,$45,$74,$45, $AF, $E4,$ 119, $64 
; C offsets for modifier keys) 
DC.W $6 173, $6466, $6867, $7978, $6376, $62, $7177, $6572 
DC .W $AEC6, $CEB2, $8000, $7EB5 , $C909, $CAD4 , $800 
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data9 ; Old Mac key translate table (German keyboard) 
DC.W $10,$45,$74,$45, $AF , $E4,$ 119, $E4 
; © offsets for modif ier keys) 
DC.W $6 173, $6466 , $6867, $3C79, $7863, $2076, $7177, $6572 


. CDC.W offsets for modifiers etc.) 


DC.W SAEF 1, $CEOD, $F7C9, $F5F6,$F809,$3D4, $8CA 


comi LEA proc2,Að 
MOVE.L A,KeylTrans ; $29E 


RTS 
; numeric keypad translator 
INIT! BRA com_1 ; setup jump vector 
proc2 LEA data1,A0 ; translate table 
CMPI.B #11,KybdType ; 11 = Mac* 
BEQ.S  lac.1 
ADDA.W 564,40 ; offset for old Mac 
lac-1 LSR #1,D1 
BCC.S  lac.2 


ADDA.W %32,A8 ; offset for shift key 
lac.2 ANDI.B #$1F,D2 
MOVE.B ØCAG,D2.W),DØ ; get table entry 
RTS 
data! DC.W $2C,$1000,0,$ 1C 18,$ 1F00 0,$31E, $2000 
DC.W 0,$3031,$3233,$3435, $3637, $38, 3900 , 0 
DC.W $2E,$2400,0,$2B 18, $3000, 0, $32F ,$2000 
DC.W 0,$3031,$3233,$3435,$3637,$38,$3900,0 
DC.W $2C,$1000,0,$1C18,$ 1F00,0,$31E, $2000 
DC.W Ø , $303 1, $3233, $3435, $3637, $38, 3900 , 0 
DC.W $2C,$2400,0,$28 18, $2E00, 0, $32F , $2000 
DC.W 0,$3031,$3233,$3435,$3637,$38,$3900,0 


com..1 LEA proc2,A0 
MOVE.L AQ,Key2Trans 
RTS 


END 


Listing 2: Reconfiguring the Keyboard routines 
INIT $ and INIT 1 


( Keyboard reconfigurator, c 1986 J. Langowski / MacTutor ) 
( For reconfiguration of individual keys without using the 
Localizer ) 


only forth also assembler also mac 


hex 

494e4954 constant “init 

2]e constent keyb.type ( B: Mac* ) 
variable hand’ variable hand! 


: get .handles 
"init Ø call getresource hand ! 
"init 1 call getresource hand! ! 


: get.keyl.data ( | handle start.of data ) 
handü @ dup @ 7fffff and 14 + 
keyb. type cê B «> if C + then dup wê + 


: get.key2.data ( | handle start.of date ) 
hand! @ dup @ 7fffff and 6 + dup we + 
keyb. type cê B € if 40 + then 


keyin 
begin 2d emit 8 emit ?terminal ?dup until 


keycode ( extracts keycode out of keyinfo ) 
100 / ff and ; 


: modifiers ( extracts modifiers from keyinfo ) 
1000000 / ff and ; 
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: keyaddress ( | mods keyc -- handle offset ) 
dup modifiers -? mods keycode -? keyc 
keyc 41 < if get.keyl.data 

dup mods E and + wê + keyc + 
else get .key2.date 
mods 2 and 
if € shift key down) 28 + then 
keyc 1f and * 
then 


| keytest 
begin keyin keyaddress c@ emit key drop drop again 


: get&show ( | handle offset ) 
keyin dup key emit ." - Keycode = 
dup modifiers swap keycode . 
." , Modifiers = " binary 
(2 8 " 8 " ") tune decimal 
keyaddress dup cê 
" , actual mapping - " emit cr 


: keynum cr 
begin get&show drop drop again 


decimal 
: hello 

cls 

." Macintosh Keyboard Remapper" cr 

." € 1986 J.Lengowski / MacTutor" cr cr 

." Closing the window will update the resource file." 
er cr 


: yesno begin key dup emit 
case 
89 of 1 1 endof 121 of 1 1 endof 
78 of Ø 1 endof 118 of Ø 1 endof 
cr ."yor n - " f swap 
endcase 
until 


: on.goaway Ø call updateresf ile bye ; 
: remap 
hello 
get . handles 
begin 
." Type the key you'd like to change - " cr 
get&show C | handle offset ) 


." Do you want to remap this key (y/n) - " yesno 
cr 

if 
." Enter the character to map this key to - " 
key dup emit cr 
swap c! 

( store in mapping table of INIT resource) - 

call changedresource 

else 2drop 

then cr 

again 


164 user goaway-hook 

NEW. WINDOW remapper 

" Keyboard Configuration Editor" remapper TITLE 

90 20 316 496 remapper BOUNDS 

ROUNDED VISIBLE CLOSEBOX NOGROWBOX 
remapper ITEMS 

609 5000 terminal mapper 

: go.map activate remap ; 

: Start 
remapper add 
remapper mapper build 
['] on.goaway goaway-hook task-? mapper ! 
remapper dup call selectwindow call setport 
mapper go.map 


Forth Forum 
An Edit Task for Forth 


An Editor Task For Mach2 
By Juri Munkki, with Jérg Langowski 

{Since this column is the Forth Forum, we must give others 
space for contributions. This month we received an article by one 
of our readers, Juri Munkki from Helsinki, who devised a rather 
practical text editor to run under Forth. Evidently they lack a desk 
accessory editor like MockPackage+ which will run with HFS. 
With the multi-tasking Mach2, an editor task helps a lot in 
developing programs; I had the same problems as Juri trying to 
use Edit 2.0 in connection with Mach2. Mach2 and Edit just don't 
want to run together under Switcher - even with the cache 
switched off - on a Mac Plus. Also, Edit is overkill for Forth 
development since individual program pieces tend to be rather 
short. 

The 32K text size limitation for this editor is therefore no big 
drawback; in fact, itis more than the 28K of MockWrite. Read the 
code carefully for some interesting additions to Mach2, like ON, 
OFF, ANEW, scrap handling words, an on-window palette 
menu and auto-indentation on text entry. 

Enough of a foreword, I'll pass the keyboard to Juri now. 
J.L.] 

Editing a Problem in Mach 2 

Mach 2 is a great language, but it certainly has some flaws. 
The first one that every programmer confronts is the lack of an 
integrated editor. 

Palo Alto Shipping suggests that Edit and Forth are used with 
Switcher, but I don't like Edit and and it takes most of my 512K 
Mac's memory to hold Mach I, Edit and Switcher. The first thing 
thatcame to my mind was MockWrite. MockWrite is a very good 
text editor DA, but the versions everybody have here in Finland 
trash files under HFS. (I had a lot of fun finding that out.) 

I didn't know of any other DA editors when I got Mach I, so 
I thought writing a small editor would not take too much time. 

I still had to find a working combination in order to be able 
to write the editor. The best solution I found, was to use Edit and 
Mach without the Switcher. In Edit, I could use "Other" to launch 
Forth and in Mach, I used an FKEY to launch Edit. I modified the 
menu in Edit so that I could switch programs with a command key 
combination. With the cache on, it wasn't unbearably slow, but 
it wasn't very interactive. 

I have done most of my Macintosh programming in Mac- 
Forth because it was the first good language available. Mach I is 
different, but learning it was easy since the manual is good and 
I already knew the toolbox. I wouldn't recommend Mach I to a 
beginner, but it is very good as a second language. I still miss 
many of the nice little commands that MacForth has. 

Iextended Mach I with some MacForth words that I thought 
would be useful. Anew was probably the most important. 
In.Heap would also have been nice, but HeapVar was the best I 
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could do with my knowledge of Forth. Heapvar is used to return 
the heap space that is pointed to by the handle in a variable. I also 
added RECT, 'RECT, ON and OFF. On and Off are very simple, 
but they make code much more readable and speed up programs. 

Example of "HeapVar": 

HeapVar A.Variable 

Anew MyProgram 

Variable A. Variable 


100 Call NewHandle Drop A.Variable ! 


The editor uses the ROM TextEdit engine and is thus limited 
to a maximum of 64K of text or 32767 lines. I have limited the 
editor to 32K of text in order to avoid checking for the maximum 
amountof lines. The commented source code of TEDDY is about 
25K. This limits the amount of source code to 32K, but code 
segments are not allowed to be larger than 32K. 

Teddy is not the first Editor I have written. I wrote a similar 
program in MacForth when I thought it would be a nice addition 
to my terminal program. The MacForth version of Teddy is even 
simpler than MachTeddy, but the experience helped me avoid 
some bugs and problems. 

The program conforms closely to the Macintosh user inter- 
face guidelines. The only nonstandard thing I can think of is the 
lack of an I-beam cursor. I forgot the cursor at first, but when I 
thought of it, it no longer seemed worth adding. This is a 
programmer's tool, after all. My MacForth Teddy has an I-Beam 
cursor, since it is used by non-programmers who expect it. 

The comments in the program demonstrate the things that 
have been less documented in MacTutor. Scrap handling is 
heavily documented because the program does it 100% accord- 
ing to Inside Macintosh and it has not been discussed in MacTu- 
tor. Inside Macintosh gives very specific rules on scrap manage- 
ment. 

The scrap is usually held in two places. The desk accessories 
expect it to be in the desk scrap and every program usually has its 
own clipboard format. Text Edit has two global variables to 
handle the clipboard. The TE-scrap must be converted to the 
global scrap after a cut or paste has been made. 

Teddy avoids useless scrap conversion. If a program first 
converts the scrap to text and then puts it back without a change, 
all others' formats are lost. Consider a situation where a user has 
three programs under Switcher and two of these understand 
pictures. If a picture is copied and then the user switches to the 
other program, by first switching to the text application, the text 
application should not delete the picture just because it doesn't 
like pictures. Destroy the desk scrap only when you have to 
change it! 

Teddy keeps a flag to monitor changes in the text edit scrap. 
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If a cut or copy is made, the flag is set and the scrap will be 
converted when the window is deactivated. Desk scrap is always 
moved to the text edit scrap if the editor window is activated. 

Menus are a very good invention, but sometimes a palette on 
a window is easier and faster to use. My first experiment with 
palettes was with the MacForth version of Teddy. I have used 
them since then on many of my programs. It would be very easy 
to add keyboard equivalents to these functions, but Teddy has 
none. A palette is very simple to implement: it is a collection of 
boxes that act like buttons. I first tried to use a collection of 
buttons, but a button takes too much space. 

Teddy scrolls automatically if the user tries to type outside 
the screen. The selection range is used to determine if the screen 
should be scrolled. Cursor keys work well, because the person 
who wrote Text Edit was clever enough to implement them. 

Clickloop procedures are very hard to do in Forth, so I wrote 
the scroll routine in assembler. The clickloop routine changes the 
setting of the scroll bar, but the changes are not drawn during the 
scrolling because Text Edit sets the clipping rectangle to the text 
edit view rectangle. If you want to be able to monitor the selection 
from the scroll bar, insert a few toolbox calls to change the 
clipping rectangle. 

The Macintosh File Manager is easy to use (once you figure 
out how), but requires a large amount of initialization. I haven't 
figured how to use the Mach 2 file system, so it wasn't really hard 
to write the routines in "pure toolbox" instead of Forth. Note that 
HFS is supported simply by using the volrefnum from the sfreply 
and putting it in the parmblock. The current (last used) filename 
and volrefnum are remembered for later use. Loading and saving 
stop multitasking. 

The "Enter" key is useless in MacWrite, but in this editor it 
provides an indenting alternative to the "Return" key. You might 
want to switch the meaning of return and enter. Enter looks at the 
line you are on, adds a return and a few spaces to align the new 
line with the previous line. Tab generates four spaces. 

When I write programs, I use a workspace that contains 
Teddy and some extensions. The resources (DLOG, ALRT, 
DITL, PICT) are in the Mach 2 file because that way they aren't 
deleted when the workspace is updated. Teddy should be snap- 
shotted before it is called, or the workspace will not work. 

Teddy might serve as a basis for creating more specialized 
editors. You may use this source code in any program you write, 
but it would be nice to mention me in the "About" dialog. 

Iusually edita program, save it and load it from a file because 
this forces me to make constant backups to the disk. Even a very 
small cache is enough to keep the file in RAM and compiling is 
just as fast as compiling from the clipboard. 

Let's program! 

Installation Notes - J.L. 

To install the editor in your Mach2 (or Mach1) system, you 
should create a Workspace immediately after loading the file by 
either saying workspace ted or new-segment ted (the latter 
leaving a full 32K of code space after the editor has been 
invoked). Make sure the workspace file is on the same disk as the 
copy of Mach? that it is run with, otherwise the workspace won't 
Work. 
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You can then, as usual, click the workspace icon and call the 
editor from within Mach by typing ted. The resources used by the 
editor should be in the Mach file (see above). Listing 2 shows an 
Rmaker input to create those resources, which can then be pasted 
with ResEdit. The PICT ID=900 is not printed here. However, it 
is on the resource file Teddy.rsrc on our source code disk. I'd 
recommend you to get that disk anyway instead of typing in all 
the code. 
Listing 1: Teddy, A Text Editor Task for Machi. 
C Teddy -- Text Editor ) 
€ Contains MacForth-like extensions to Mach I in addition to 
the editor. Type TED to call the editor at any time. The 
MacForth-style extensions are mostly undocumented here. 
Look for examples in this source. ) 
( Anew: 
Used in the form: ANEW PROGRAM.NAME. It tries to find the 
PROGRAM_NAME and forget it if it is found. It then creates 
PROGRAM_NAME and continues. It should be used in the 
beginning of the program. Old versions are then automatically 
forgotten, if they exist. ) 
ONLY FORTH DEFINITIONS 
ALSO MAC ALSO ASSEMBLER 
: ANEW ( | LEN ) 

32 WORD DUP C@ 1+ NEGATE -> LEN 

FIND SWAP DROP 

IF LEN >IN +! FORGET CALL DRAWMENUBAR THEN 

LEN >IN +! 
CREATE DOES» DROP 


ry 


( Heapvar: Used in the form: HEAPVAR VARIABLE_NAME. If 
VARIABLE.NAME exists, it returns the handle from 
VARIABLE_NAME to the heap. It should be used before 
ANEW to free space from the heap. ) 

: HEAPVAR 

32 WORD 
FIND IF LINK^BODY EXECUTE 
@ DUP 
IF DUP CALL HUNLOCK DROP 
CALL DISPOSHANDLE DROP ELSE DROP THEN 
ELSE DROP 
THEN 


: RECT 

CREATE SWAP 2SWAP SWAP W, W, W, W, 
GLOBAL 

CODE !RECT 

MOVE.L 

MOVE.W 

MOVE.W 

MOVE.W 

MOVE.W 

ADDA .L 

RTS 
END-CODE 
GLOBAL 

CODE OFF 

MOVEA.L — (A62*,A0 

CLR.L — (A0) 

RTS 
END-CODE 
MACH 
GLOBAL 

CODE ON 

MOVEA.L 

MOVE.L 

RTS 
END-CODE 
GLOBAL 

CODE SCALE 


(A6)*, A0 
14(A6), CAB)+ 
10(A6), (AB)+ 
6(A6), CAD )+ 
2(A6), CAD )+ 
#16, AG 


(A6)*,A0 
8-1 (AQ) 
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MOVE.L — (A62*,00 
BMI.S ei 
MOVE.L — (462,1 
ASL.L — 00,D1 
MOVE.L D1, CA6) 
RTS 

@1 MOVE.L (A6),D! 
NEG.L DØ 
ASR.L — D0,D1 
MOVE.L — D1,CA6D 
RTS 

END-CODE 

GLOBAL 


CODE @MOUSE 


SUBQ.L — 54,46 
MOVE.L — 46,-CATD 
_GETMOUSE 

RTS 


END-CODE 

HEADER TEDDY.W2 DC.L Ø 

HEADER TEDDY.T2 DC.L Ø 

HEADER TEDDY.S2 DC.L Ø 
CODE CLICKPROC 


e4 


e3 
ei 


MOVEM.L — D1-D3/A9-M, -CAT) 
) 


CLR.L -(A7 

MOVE.L AT,-CAT) 

-GE TMOUSE C Where is the mouse cursor? ) 
MOVE.L (A7)*,D0 

SWAP .W DØ C Get the Y-location to DØ.Ww ) 
CMP .W #18, D9 € Is Mouse.Y smaller than 18? ) 
BLT.S e1 

MOVE.L TEDDY .W2, Ad 

MOVE.W 2ØCA0),D1 


SUB.W #16,D1 


CMP .W D1,D8 ( Is Mouse.Y below the text? ) 


BGE.S e2 

MOVEM.L — (A72*,D1-D3/A0-A4 

MOVEQ.L 1,08 

RTS 

CLR.W -(AT) ( Are we allowed to scroll down? ) 
MOVE.L TEDDY .S2, -CA7) 

-GETCTLVALUE 

MOVE.W CA7)+,D8 

BEQ.S 84 (C If we are on top, do nothing ) 
SUBQ.W — *1,00 ( Scroll one line up ) 

MOVE.L TEDDY .$2, -CA7) 

MOVE.W — D0,-CATD 

-SETCTLVALUE 

CLR .W -(AT) 

MOVE.W %11,-CA7) C One line = 11 pixels ) 

MOVE.L TEDDY . T2, -CA7) 

—TESCROLL C Scroll the text ) 

MOVEM.L — CA72*,D1-D03/A0-A4 

MOVEQ.L  *1,D0 

RTS 


@2 CLR.W ~CAT) 


MOVE.L TEDDY .$2,-CA7) 

-GETCTLVALUE C Where are we? ) 
MOVE.W CA7)+,D3 

CLR. W -(AT) 

MOVE.L TEDDY .$2,-CA7) 

-GETMAXCTL ( How high can we go? ) 
MOVE.W (AT)*,00 

CMP .W D0,D3 

BGE .S 84 

ADDQ.W #1,D3 € Scroll one line... ) 
MOVE.L TEDDY .S2, - CAT) 

MOVE.W D3,-CA7) 

-SETCTLVALUE 

CLR .W -(AT) 

MOVE.W 8-11,-CAT) 

MOVE.L TEDDY . T2, -(A7) 

-TESCROLL 

MOVEM.L — CA72*,D1-D3/A0-A4 
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MOVEQ.L 1,08 
RTS 
END-CODE 
( The following routine is quite simple. All it does is search a 
string for another one ignoring case and it returns the offset or 
a flag. ) 
CODE FINDER 
( ?STR ?LEN SEARCHSTR SEARCHLEN —- OFFSET ) 


MOVEM.L — D2-D7/A0-A4,-CA7) 
MOVE.L (A62*,D0 
MOVE.L (A62*,A0 
MOVE.L (462*,01 
MOVE.L CA6)+,A1 
MOVE.W 06,02 
SUB.W D1,D2 
CLR.L D7 
@1 CLR.W D3 
@2 MOVE.B  ØCAG,D3.W),D4 
BMI.S e3 
CMP .B #96 D4 
BLT.S e3 
SUB.B #32,D4  ( Remove case ) 
@3 MOVE.B — 8(A1,03.W2,05 
BMI.S 84 
CMP.B #96,D5 
BLT.S e4 
SUB.B #32,D5 € Remove case ) 
64 CMP.B D4,D5 ( Is a char equal to another? ) 
BNE.S e5 
ADDQ.W — 1,03 ( It was, one match ) 
CMP.W D1,D3  ( Have we found the string? ) 
BLT.S e2 
MOVE.L D7,-CA6) 
MOVEM.L — CA72*,D0-D7/A90-A4 


RTS 
e5 ADDQ.L — *1,A0 


C No match... .yet ) 
ADDQ.L #1,D7 


DBRA D2,01 € Look again? ) 
MOVE.L  8-1,-CA6) C No match. ..return -1 ) 
MOVEM.L  CA7)+,DØ-D7/AB-A4 
RTS 

END-CODE 


C 4ASCII nnnn converts the 4 character string into its numeric 
value. It can only be used in the immediate mode. Examples 
below ) 

: 4ASCII 
Ü 

4 0 DO 

8 SCALE @ WORD i+ Ce + 

LOOP ; 

ONLY FORTH ALSO MAC 
4ASCII TEXT CONSTANT "TEXT 
4ASCII DRVR CONSTANT DRIVER 
4ASCII MACA CONSTANT "MACA 

HEX ABO CONSTANT TESCRAP .LEN 
( Global TeEdit private scrap variables ) 
AB4 CONSTANT TESCRAP . HANDLE DECIMAL 
NEW.WINDOW TEDDY.W 
" Text Editor" TEDDY.W TITLE 
58 Ø 304 480 TEDDY.W BOUNDS 
ZOOM VISIBLE CLOSEBOX GROWBOX TEDDY.W ITEMS 
400 4000 TERMINAL TEDDY. TASK 

NEW.MBAR TEDDY .BAR 
988 CONSTANT APPLEID 
NEW.MENU APPLEMENU 

HERE 1 C, 20 C, APPLEMENU TITLE 

" About Edit...;C-" APPLEMENU ITEMS 

Ø APPLEID APPLEMENU BOUNDS 
991 CONSTANT TFILEID 
NEW.MENU TFILE 
" File" TFILE TITLE 
" Open/0;Save/S;Save as..." TFILE ITEMS 
Ø TFILEID TFILE BOUNDS 


C Add DAs later ) 
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992 CONSTANT TEDITID 
NEW.MENU TEDITMENU 
" Edit" TEDITMENU TITLE 
" Cut/X;Copy/C;Peste/V;Select All & Copy;-C;Find/F;Again/GC" 
TEDITMENU ITEMS 
Ø TEDITID TEDITMENU BOUNDS 
: ADD.DRVRS € Add desk accessories ) 
APPLEMENU @ DRIVER CALL ADDRESMENU ; 
NEW.CONTROL TEDDY .SB 
VSCROLLBAR VISIBLE 100 @ TEDDY.SB ITEMS 
: DAHANDLER ( ITEM | Daname ) 
ITEM 2 » IF ( We must open a desk accessory ) 
256 CALL NEWPTR -» DANAME 


C Get us a STR255 for the name ) 
APPLEMENU @ ITEM DANAME CALL GETITEM 
DANAME CALL OPENDESKACC DROP 


( Open the desk accessory ) 
DANAME CALL DISPOSPTR ( Give the String back ) 
ELSE 
ITEM 1 = 
( The about edit alert should be shown. The resource must 
be added separately to Mach 2. ) 
IF 900 Ø CALL ALERT DROP THEN THEN 


L 
HEX 44 CONSTANT txFont ( Offsets in a window record ) 
46 CONSTANT txFace 
48 CONSTANT txMode 
4A CONSTANT txSize 
6C CONSTANT WindowKind DECIMAL 


VARIABLE TEDDY.T € PLACEHOLDER FOR TEXT HANDLE ) 
VARIABLE ACTIVE? € ACTIVE FLAG ) 
VARIABLE MUSTCONVERT ( SCRAP CONVERSION FLAG ) 
20 CONSTANT UPARROW C Part codes ) 
21 CONSTANT DOWNARROW 
22 CONSTANT PAGEUP 
23 CONSTANT PAGEDOWN 
129 CONSTANT THUMB 


VARIABLE CURMAX ( Current scroll bar range ) 
VARIABLE CURSET ( Current scroll ber setting ) 
: CORRECT . CONTROL . RANGE 
CURMAX € TEDDY.T @ @ 94 + Wẹ 1- Ø MAX DUP CURMAX ! 
= NOT 
IF TEDDY.SB 6 CURMAX @ CALL SETMAXCTL THEN 


: CORRECT.CONTROL < Set scroll bar ) 

CURSET @ € Look at the destination RECT for the position ) 
18 TEDDY.T @ e we L EXT - 11 / DUP CURSET ! = NOT 

IF TEDDY.SB 6 CURSET @ CALL SETCTLVALUE THEN 


é 
: TOO.HIGH. TEDDY € Autoscroll, when typing ) 

Ø TEDDY.W 20 + we 40 - TEDDY.T e e 

16 + W@ L_EXT - DUP 11 MOD - 

?DUP IFC If tescroll is called with Ø 9,the ceret disappears! ) 
TEDDY.T @ CALL TESCROLL 

ELSE DROP THEN 

CORRECT . CONTROL 


s 

: TOO.LOW.TEDDY — € Autoscroll, when typing ) 
0 29 TEDDY.T @ @ 16 + W@ L EXT - DUP 11 MOD - 
TEDDY.T @ CALL TESCROLL 

CORRECT . CONTROL 


d 
: CORRECTSCROLL 
( If the user is typing, check if we should scroll. ) 
TEDDY.T 6e @ 32 + DUP W@ SWAP 2+ We = 
C Do we have a caret? ) 

IF TEDDY.T e @ 16 + we L EXT 29 < IF TOO.LOW.TEDDY ELSE 
TEDDY.T e @ 16 + W@ L EXT 
TEDDY .W 20 + we 40 -> 

THEN 


IF T00.HIGH. TEDDY THEN 
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THEN 


4 
CREATE TEMR 8 ALLOT — C Temporary storage ) 
: SCRAP-» TE ( Convert global scrap to TeScrap ) 
Ø "TEXT TEMR CALL GETSCRAP Ø> ( Is there text? ) 
IF TESCRAP.HANDLE @ "TEXT TEMR CALL GETSCRAP 
TESCRAP.LEN W! THEN 
MUSTCONVERT OFF 


( The screp does not heve to be converted just now ) 


* TE-'SCRAP 
MUSTCONVERT e 


IF 
CALL ZEROSCRAP DROP 
( Zero screp to clear non-text entries ) 
TESCRAP.LEN W@ "TEXT TESCRAP.HANDLE @ e 
CALL PUTSCRAP DROP 


€ Are there any changes after SCRAP-?TE? ) 


THEN 


a 
: CLEAR. TESCRAP | 
€ Word used to clear tescrap when it is not needed ) 
TESCRAP.HANDLE @ Ø CALL SETHANDLESIZE DROP 
Ø TESCRAP.LEN W! 


b 


VARIABLE OLDPORT 

( Used to save the current window before a dialog ) 
CREATE DLOG9ØØ Ø , ( Handle storage for our "FIND" dialog ) 
VARIABLE DEVENT ( Dialog "event" ) 


( You cen set the following strings from Forth and then use 
"aGain" to replace any untypeable characters. 

Do a find or replace, then set teddy.f 1 and f2 and choose 
"aGain". This will do the previous operation with the new 
strings! ) 


CREATE TEDDY.F1 256 ALLOT C String to f ind ) 
CREATE TEDDY.F2 256 ALLOT C Replace string ) 
( The following part finds Teddy.F1 from the text ) 
: TFIND.REALLY ( | SELEND STRSTART ) 

TEDDY.T e e 34 + we -) SELEND 

TEDDY.T @ @ 62* € 8 -> STRSTART 

TEDDY .F 1 COUNT ?DUP 

IF 

STRSTART SELEND + 

TEDDY.T e e 60 + we SELEND - 

DUP TEDDY.F1 Ce » 


IF 
FINDER DUP 
Ø< IF — DROP 10 CALL SYSBEEP Ø Ø TEDDY.T e 


CALL TESETSELECT 
ELSE 
SELEND + TEDDY.F1 C@ + DUP TEDDY.T e 
CALL TESETSELECT 
THEN 
ELSE 2DROP 2DROP 10 CALL SYSBEEP Ø Ø TEDDY.T e 
CALL TESETSELECT 
THEN 
CORRECTSCROLL 
ELSE DROP 
THEN 


€ The following finds Teddy.F1 and replaces it with Teddy.F2 ) 
: TEDDY.REPLACE ( | SELEND STRSTART ) 

TEDDY.T @ @ 34 + we -) SELEND 

TEDDY.T @ 6062+660 -) STRSTART 

TEDDY .F 1 COUNT ?DUP 

IF 


STRSTART SELEND + 

TEDDY.T e e 60 + we SELEND - 
DUP TEDDY.F1 Ce » 

IF 
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FINDER DUP 
Ø< IF — DROP 10 CALL SYSBEEP Ø Ø TEDDY.T e 
CALL TESETSELECT 
ELSE DUP 


SELEND + TEDDY.F1 Ce OVER + TEDDY.T e 
CALL TESETSELECT 
TEDDY.T @ CALL TEDELETE 
TEDDY.F2 COUNT TEDDY.T @ CALL TEINSERT 
SELEND + TEDDY.F2 Ce + DUP TEDDY.T e 
CALL TESETSELECT 
THEN 


ELSE 2DROP 2DROP 10 CALL SYSBEEP 8 8 TEDDY.T e 
CALL TESETSELECT 


CORRECTSCROLL 


: TEDDYFIND.SUB € Find or replace according to button ) 
DEVENT We CASE 
1 OF TFIND.REALLY 
2 OF TEDDY .REPLACE 
ENDCASE 


ENDOF 
ENDOF 


J 
: TEDDYFIND 
TE-» SCRAP 
( Forth receives en ectivate when the dialog is gone. ) 
( The scrap must be saved to preserve it. ) 
TEDDY.T @ CALL TEDEACTIVATE 
DLOGOO0 @ ø= 
IF 900 Ø -1 CALL GETNEWDIALOG DLOG9ØØ ! 
ELSE DLOG9@@ @ CALL BRINGTOFRONT DLOGOOQ 6 
CALL SHOWWINDOW 
THEN 
OLDPORT CALL GETPORT 
DLOG9ØØ @ CALL SETPORT 
BEGIN 
Ø DEVENT CALL MODALDIALOG 
( Call this until the user hes finished ) 
DEVENT W@ 4 « 
UNTIL 
OLDPORT @ CALL SETPORT 
( Reset "predialog" environment ) 
DLOGO0Q @ 5 PAD PAD 4 + PAD 8 + CALL GETDITEM 
PAD 4 + € TEDDY.F1 CALL GETITEXT € Set Teddy.F1 ) 
DLOG9ØØ @ 6 PAD PAD 4 + PAD 8 + CALL GETDITEM 
PAD 4 + @ TEDDY.F2 CALL GETITEXT ( Set Teddy.F2 ) 
DLOG9ØØ @ CALL HIDEWINDOW 
TEDDY.T @ CALL TEACTIVATE 
TEDITMENU @ 7 CALL ENABLEITEM 
TEDDYF IND .SUB 


C Set the dialog port ) 


( Handle Cut/Copy/Paste and others for Teddy and DAs ) 
: TEDITHANDLER ( ITEM ) 
CALL FRONTWINDOW TEDDY.W = 
IF € Editor cut/paste ) 
ITEM CASE 
1 OF TEDDY.T @ CALL TECUT 
2 OF TEDDY.T @ CALL TECOPY 
3 OF TESCRAP.LEN We 
TEDDY.T e e 68 + we 
TEDDY.T e @ 34 + we TEDDY.T @ e 32 + we - - 
+ 32767 « IF 
TEDDY .T @ CALL TEPASTE 
ELSE 5 CALL SYSBEEP 5 CALL SYSBEEP THEN ENDOF 
4 OF Ø TEDDY.T e e 60 + we TEDDY.T e 
CALL TESETSELECT 
TEDDY.T @ CALL TECOPY MUSTCONVERT ON ENDOF 
6 OF TEDDYF IND 
ENDOF 
T OF TEDDYF IND .SUB 
ENDCASE 
CORRECT . CONTROL . RANGE 
CORRECTSCROLL 


MUSTCONVERT ON ENDOF 
MUSTCONVERT ON ENDOF 


ENDOF 
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ELSE € DA cut/copy/paste...Undo is left for you to add... ) 
CALL FRONTWINDOW 
WINDOWKIND + we L_EXT 8< 
IF ITEM 4 « 
IF ITEM 1+ CALL SYSEDIT DROP THEN 


, ALSO ASSEMBLER 
( Here we have support for SFGETFILE and SFPUTFILE; these 
routines are similer to the ones in the Mach 2 manual. ) 
HEADER TYPES DC.B 'TEXT' 
HEADER GPROMPT DC.B 20 
DC.B ‘Please select a file’ 
HEADER PPROMPT DC.B 18 
DC.B ‘Please type a name' 
CODE TEDDYGETFILE 


MOVE.W — #50 -CA7) 
MOVE.W #59, -CA7) 
PEA GPROMPT 
CLR.L — -(A7D 
MOVE.W — 81,-(ADD 
PEA TYPES 
CLR.L — -CAT) 
MOVE.L — (A62*,-(AT) 
MOVE.W #2, CAT) 
-PACK3 
RTS 

END-CODE 

CODE TEDDYPUTFILE 
MOVE.W  #5Ø,-CA7) 
MOVE.W #50, -CA7) 
PEA  PPROMPT 
MOVE.L  (A6)#,-CA7) 
CLR.L — -(ADD 
MOVE.L — (A62*,-(A7D 
MOVE.W — 1,-CA7) 
-PACK3 
RTS 

END-CODE 


ONLY FORTH ALSO MAC ALSO TALKING 
230 USER PARMBLK 
CREATE FNAME Ø C, 63 ALLOT 
C Our file has a name. This is where it is kept) 
CREATE FPLACE @ , ( This is the folder of our file. HFS! ) 
( Here we do some "dirty" programming. I use the file manager 
directly. This works, but the code is not very clear. Once the 
PAReMeterBLocK is set, it doesn't need to be changed much. 
Read Inside Macintosh for details on parameter blocks and 
the file system. ) 
: TEDDYLOAD € Replace selection range with a file ) 
TE-? SCRAP 
PAD TEDDYGETFILE C Use PAD as SFREPLY ) 
PAD C@ IF PAD 10 + FNAME 64 CMOVE 
PAD 6 + We FPLACE ! 
PARMBLK 12 * OFF 
PAD 18 + PARMBLK 18 + ! 
PAD 6 + W@ PARMBLK 22 + W! 
9 PARMBLK 26 * W! 
PARMBLK 28 * OFF 
PARMBLK CALL OPEN 
IF 10 CALL SYSBEEP € Ouch! File Error ) 
ELSE 
PARMBLK CALL GETEOF DROP 
PARMBLK 28 + @ 
TEDDY.T e @ 60 + we 
TEDDY.T e e 34 + we TEDDY.T @ @ 32 + We - - 
+ 32767 « € Does the result fit? ) 
IF TESCRAP.HANDLE @ DUP DUP 
PARMBLK 28 + @ CALL SETHANDLESIZE DROP 
CALL GETHANDLESIZE TESCRAP.LEN W! 
CALL HLOCK DROP 
TESCRAP.HANDLE @ @ PARMBLK 32 + ! 
TESCRAP.LEN W@ — PARMBLK 36 + ! 
Ø PARMBLK 44 + W! 
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Ø PARMBLK 46 + ! PARMBLK CALL DELETE 
PARMBLK CALL READ DROP ELSE 


TESCRAP.HANDLE @ CALL HUNLOCK DROP PARMBLK CALL GETFILEINFO DROP 
PARMBLK CALL CLOSE DROP "TEXT PARMBLK 32 * ! 
TEDDY.T @ CALL TEPASTE "MACA PARMBLK 36 * ! 
CORRECT . CONTROL . RANGE PARMBLK CALL SETFILEINFO DROP 
CORRECTSCROLL THEN 
ELSE 5 CALL SYSBEEP 5 CALL SYSBEEP PARMBLK 18 * OFF 
( Ouch! Text too long ) PARMBLK CALL FLUSHVOL DROP 
THEN THEN THEN 
THEN ; 
THEN : TFILEHANDLER € Handle the file menu ) 
P CASE 1 OF Ø TEDDY.T e e 60 + we 
: TEDDYSAVE € Save selection range ) TEDDY.T @ CALL TESETSELECT 
TE-> SCRAP TEDDYLOAD ENDOF 
PAD FNAME TEDDYPUTFILE 2 OF TEDDYSAVEALL ENDOF 
PAD C@ IF PAD 10 + FNAME 64 CMOVE 3 OF TEDDY.T @ @ 32 + @ 
PAD 6 + We FPLACE ! Ø TEDDY.T @ 8 32 + ! 
PARMBLK 12 * OFF TEDDYSAVE 
PAD 10 + PARMBLK 18 + ! TEDDY.T @ @ 32 + ! ENDOF 
PAD 6 + W@ PARMBLK 22 + W! ENDCASE 
Ü PARMBLK 26 * W! 3 
PARMBLK 28 + OFF : TEDDYMENUS ( Menu events are delivered here ) 
PARMBLK CALL CREATE DROP Ø CALL HILITEMENU 
PARMBLK CALL OPEN DROP CASE 
TEDDY.T @ @ 34 + W@ TEDDY.T @ @ 32 + We - APPLEID OF DAHANDLER ENDOF 
?DUP Ø= IF TEDDY.T @ e 60 + W@ THEN TFILEID OF TFILEHANDLER ENDOF 
PARMBLK 28 * ! TEDITID OF TEDITHANDLER ENDOF 
PARMBLK CALL SETEOF DROP ENDCASE 
TEDDY.T e e 34 + we TEDDY.T e e 32 + we - ; 
2DUP Ø= IF ( This program has a menu on its window. There are 5 items on 
TEDDY .T e e 60 + W@ PARMBLK 36 + ! this menu and the names of these items have to be kept 
TEDDY.T @ @ 62 + @ @ PARMBLK 32 + ! Somewhere. This was a simple way to create an array of 
ELSE strings. ) 
PARMBLK 36 + | : TITLES 
TEDDY.T e @ 62 + e e TEDDY.T e @ 32 + we + CASE Ø OF " Select A11" ENDOF 
PARMBLK 32 * ! 1 OF " Select Forward" ENDOF 
THEN 2 OF " Select Backward" ENDOF 
Ø PARMBLK 44 + W! PARMBLK 46 + OFF 3 OF " Copy From Disk" ENDOF 
PARMBLK CALL WRITE 4 OF " Save Selection" ENDOF ENDCASE 
PARMBLK CALL FLUSHFILE DROP ; 
PARMBLK CALL CLOSE DROP : DRAWTITLES ( Drew palette items ) 
IF 18 CALL SYSBEEP PAD CALL GETPORT € Get our window ) 
PARMBLK CALL DELETE PAD @ TXFONT + W@ C Save text characteristics ) 
ELSE PAD @ TXSIZE + we 
PARMBLK CALL GETFILEINFO DROP PAD @ TXMODE + We 
"TEXT PARMBLK 32 + ! € Text filestype TEXT! ) 1 CALL TEXTFONT C Geneva ) 
"MACA PARMBLK 36 + ! ( MacWrite files ) 9 CALL TEXTSIZE ( 9 point ) 
PARMBLK CALL SETFILEINFO DROP 1 CALL TEXTMODE 
THEN 5 8 DO ( 5 items in our palette ) 
PARMBLK 18 * OFF 2 I 98 * 2+ 15 OVER 91 + TEMR !RECT 
PARMBLK CALL FLUSHVOL DROP TEMR CALL ERASERECT 
THEN TEMR CALL FRAMERECT 
j I 90 * 47 + 
: TEDDYSAVEALL € Save the whole file ) I TITLES CALL STRINGWIDTH 2/ - € Center the string ) 
TEDDY.T e @ 60 + we IF 12 CALL MOVETO I TITLES CALL DRAWSTRING 
TE-? SCRAP LOOP 
FNAME Ce IF CALL TEXTMODE C Reset text charesteristics ) 
PARMBLK 12 * OFF CALL TEXTSIZE 
FNAME PARMBLK 18 * ! CALL TEXTFONT 
FPLACE @ PARMBLK 22 + W! ; 
ð PARMBLK 26 + W! 168 USER UPDATE-HOOK ( Mach 2 has a lot of stupid hooks ) 
PARMBLK 28 + OFF 152 USER CONTENT-HOOK ( I have to live with them ) 
PARMBLK CALL CREATE DROP 172 USER ACTIVATE-HOOK € even if I do not like them ) 
PARMBLK CALL OPEN DROP 
TEDDY.T @ @ 60 + W@ PARMBLK 28 + ! CREATE SPORT 4 ALLOT ( Saved Port ) 
PARMBLK CALL SETEOF DROP 
TEDDY.T @ @ 60 + W@ PARMBLK 36 + ! : GROWB € Set the view rectangle ) 
TEDDY.T e @ 62 + @ @ PARMBLK 32 + ! TEDDY .W 20 + W@ 16 - 16 SCALE 
Ø PARMBLK 44 + W! PARMBLK 46 + OFF TEDDY .W 22 + We 16 - + TEDDY. Te @ 12 +! 
PARMBLK CALL WRITE : 
PARMBLK CALL FLUSHFILE DROP : TEDDYUP € Update events are delivered here ) 
PARMBLK CALL CLOSE DROP ( Note that the zoom box also generates an update event! ) 
IF 10 CALL SYSBEEP SPORT CALL GETPORT ( Save some external window ) 


O The Complete MacTutor, Vol. 2 455 


TEDDY .W CALL SETPORT 


( Use the text editor window for updates ) 


TEDOY.WN CALL BEGINUPDATE 


GROWB 


( Inside Mac says this must be done ) 


TEDDY.W 16 * CALL ERASERECT 


DRAWTITLES 


( Erase area to be updated ) 
C Drew palette titles ) 


TEDDY.W 16 + TEDDY.T @ CALL TEUPDATE 
TEDDY.W CALL DRAWCONTROLS 


( We have a scroll bar to update ) 


TEDDY.W CALL DRAWGROWICON 
TEDDY.W CALL ENDUPDATE 
SPORT 6 CALL SETPORT 


( Given the number of the palette item that the mouse wes 
pressed in, this procedure tracks the mouse to see what the 


( Restore the port before the update ) 


user really wants. ) 
: DOPALETTE.SUB ( SELECTED | SLOC ) 
3 SELECTED 90 * 3 + 14 OVER 89 + TEMR !RECT 


9 -> SLOC 
BEGIN 

CALL STILLDOWN 
WHILE 


@MOUSE TEMR CALL PTINRECT Ø= Ø= SLOC XOR 
IF TEMR CALL INVERTRECT SLOC NOT -> SLOC THEN 


REPEAT 
SLOC IF TEMR CALL 


INVERTRECT SELECTED 1+ ELSE Ø THEN 


* DOPALETTE ( There is a mousedown in the palette ) 


eMOUSE L_EXT 


2 - 90 / DOPALETTE.SUB 
CASE 1 OF Ø TEDDY.T e @ 68 + we 
TEDDY.T @ CALL TESETSELECT ENDOF 


2 OF TEDDY. 
TEDDY. 


T e @ 32 + We TEDDY.T e e 60 + We 
T @ CALL TESETSELECT ENDOF 


3 OF Ø TEDDY.T e @ 34 + we 


TEDDY. 
4 OF TEDDYLOAD 
5 OF TEDDYSAVE 


ENDCASE 


T @ CALL TESETSELECT ENDOF 
ENDOF 
ENDOF 


( Dotextclick looks at the shift key and calls TeClick. 
B= Ø= is the equivalent of MacForth's "Boolean". ) 


: DOTEXTCLICK € MOUSEPT -- Click...no ammo in a mouse... ) 
EVENT-RECORD 14 + We 512 AND Ø= Ø= TEDDY.T 6 CALL TECLICK 


TEDDY.W CALL DRAWCONTROLS 


) 


2 2 15 452 RECT BUTTONRECT ( This is the rect of our palette ) 


: CONTENTCLICK ( | MOUSEPT ) 


RUN-CONTENT 


TEDDY.W CALL SETPORT 
EVENT-RECORD 10 + @ PAD ! PAD CALL GLOBALTOLOCAL 


PAD 6 -» MOUSEPT 


MOUSEPT BUTTONRECT CALL PTINRECT 


IF DOPALETTE 


ELSE MOUSEPT TEDDY.T @ @ 8 + CALL PTINRECT 


IF MOUSEPT 
THEN 
THEN 


( We set the dest 
: INITTEXT 


DOTEXTCLICK 


end view rectengles ) 


18 4 TEDDY.W 20 + Wwe 16 - TEDDY.W 22 + we 16 - 
TEMR !RECT TEMR PAD 8 CMOVE 


1 PAD 2+ W! TEMR 


PAD CALL TENEW TEDDY.T ! 


-1 TEDDY.T e e 72 +W! 


( The following code handles the scroll bar ) 


€ The thumb is called separately...Mach I manual for details ) 


: DOTHUMB 
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TEDDY.T @ @ Wê L_EXT 18 - NEGATE 
TEDDY .SB @ CALL GETCTLVALUE 11 * - 
Ø SWAP TEDDY.T @ CALL TESCROLL 


* DOARROW 
TEDDY.SB e 


CALL GETCTLVALUE SWAP OVER * 


TEDDY.SB @ SWAP CALL SETCTLVALUE 


TEDDY.SB e 


CALL GETCTLVALUE - 


11 * Ø SWAP TEDDY.T @ CALL TESCROLL 


: TEDDYBAR 
CASE 
UPARROW OF 
DOWNARROW OF 
PAGEUP OF 


PAGEDOWN OF 
ENDCASE 
* TEDDYCONTROL 


-] DOARROW ENDOF 


1 DOARROW ENDOF 


TEDDY.W 28 + We 40 - -11 / -1 MIN DOARROW ENDOF 


TEDDY.W 20 + we 40 - 


( Control ) 


CASE € In cese of multiple controls... ) 
TEDDY.SB @ OF TEDDYBAR ENDOF 


ENDCASE 


: TEDDYCONTROL2 C Control/Part ) 
CASE € In cese of multiple controls and parts... ) 


ENDCASE 


TEDDY.SB e OF 


CASE THUMB OF DOTHUMB ENDOF ENDCASE 


ENDOF 


( We go to sleep when we are not in use. Deactivate events 


look like Act 
enough ) 


ivate events if the program doesn't look hard 


: ACTIVATE-HANDLER 


RUN-ACTIVA 


TE 


EVENT-RECORD 14 * W8 1 AND 
IF WAKE STATUS TASK-> TEDDY.TASK W! 


ACT 


IVE? ON 


TEDDY.T @ CALL TEACTIVATE 


SCR 
ELSE SLE 
TED 
ACT 
TE- 
CLE 
THEN 


( The Enter ke 
: TEDDY.ENTER 
TEDDY.T @ @ 6 
TEDDY.T e e 3 
Ø -> NSPACES 
BEGIN 
LOCATION CNT 
CNTER 1+ Ø> 
WHILE 
LOCATION CN 


CNTER 1- -> 
REPEAT 
13 TEDDY.T @ 
NSPACES Ø> IF 
NSPACES @ DO 
32 TEDDY.T @ 
LOOP THEN 


( These are do 


AP-> TE 

EP STATUS TASK-> TEDDY.TASK W! 
DY.T @ CALL TEDEACTIVATE 

IVE? OFF 

»SCRAP 

AR. TESCRAP 


does indentation, return doesn't ) 
1 | LOCATION CNTER NSPACES ) 


2+@@ -> LOCATION 
2 + W 1- -> CNTER 
ER + C@ 13 = NOT 
AND 
TER + Ce 32 = IF NSPACES 1+ -> NSPACES 
ELSE Ø -> NSPACES THEN 
CNTER 
CALL TEKEY 
CALL TEKEY 


ne only once, so we have a flag to show if the 


routine must be called. Always Workspace before testing 
TEDDY or you will save the flag in the wrong state! ) 
CREATE CONFIGFLAG Ø, 

: CONFIGURE . TEDDY 


TEDDY.W ADD 
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11 / 1 MAX DOARROW ENDOF 


TEDDY.W TEDDY. TASK BUILD 


TEDDY .BAR ADD , 108225 
TEDDY.BAR APPLEMENU ADD * | 
TEDDY.BAR TFILE ADD BtnItem Enabled 
TEDDY.BAR TEDITMENU ADD 168 312 189 344 
TEDDY.W TEDDY.SB ADD Ok 
INITTEXT 
ADD .DRVRS * 2 
TEDDY.BAR  TEDDY.TASK MBAR> TASK Piclem Disabled 
TEDDY. TASK 8 16 147 99 
CONFIGFLAG ON ; 901 
( The following can be done the first time ) 
: TEDDYGO * 3 
CONF IGFLAG @ NOT IF CONFIGURE.TEDDY ACTIVATE THEN StatText Disabled 
ACTIVE? OFF 16 168 32 248 
['] TEDDYMENUS MENU-VECTOR | Teddy V1.0X9D 
['] TEDDYUP UPDATE-HOOK ! 
['] CONTENTCLICK CONTENT-HOOK  ! * 4 
['] ACTIVATE-HANDLER ACTIVATE-HOOK  ! 
['] TEDDYCONTROL TEDDY.SB4 + ! StatText Disable 
['] TEDDYCONTROL2 CONTROL-VECTOR ! 40 144 56 280 
['1 CLICKPROC TEDDY.T e @ 42 + ! Mach 2 
190 CURMAX ! CORRECT.CONTROL . RANGE * text editor VZD 
TEDDY.SB e [') TEDDY.S2 ! 
TEDDY .W ['] TEDDY.W2 ! * 5 
TEDDY.T 68 [') TEDDY.T2 ! StatText Disabled 
BEGIN ( This is the beginning of our "Event" loop ) 
ACTIVE? @ IF TEDDY.T @ CALL TEIDLE C Caret blink, blink, blink...) 64 120 80 320 
?TERMINAL ?DUP IF Copyright ©1986, Juri Munkki 
1 24 SCALE AND IF ( Is it a cmd key? ) 
KEY CALL MENUKEY DROP , 9008 
ELSE x] 
KEY CASE 
3 OF TEDDY .ENTER ENDOF | BtnItem Enabled 


9 OF 4 Ø DO 32 TEDDY.T @ CALL TEKEY LOOP ENDOF 
TEDDY.T @ CALL TEKEY Ø € EndCase drops! ) | 64 8 88 96 


ENDCASE Find 
CORRECTSCROLL € Autoscrolling ) 
CORRECT . CONTROL . RANGE *2 
CORRECT .CONTROL 
THEN BtnItem Enabled 
THEN 
THEN 64 104 88 192 
PAUSE € This is the equivalent of GetNextEvent ) Replace 
AGAIN ; *3 
: TED StatText Enabled 
( TED always starts the editor...even if you hide the window ) 8 8 24 48 
CONFIGFLAG @ NOT IF TEDDYGO THEN Find: 
TEDDY .W CALL SHOWWINDOW *4 
TEDDY .W CALL SELECTWINDOW StetText Disable 
TEDDY.BAR @ CALL SETMENUBAR 32 8 48 70 
CALL DRAWMENUBAR Replace: 
QUIT »* 5 
jListing 2: Teddy.R, resource listing for editor. EditText Enabled 


[This file should be compiled with Rmaker and the resulting 8 80 24 424 
resources pasted into your Mach2 file with ResEdit. The picture * 6 
is contained within the file Teddy.rsrc which is available on the EditText Enabled 


MacTutor source disk for this issue. JL) 32 80 48 424 

*  ReditX 1.1, resource decompile option. * 7 

x BtnItem Enabled 
* Resource listing from file: "Teddy.RSRC". 120 104 144 19 
x 


Replace A11 
Teddy.RSRC.rsrc 8 
StatText Disabled 


Type DLOG 56 296 89 423 
Editor 1.0X0001986 Juri Munkki 
, 900 Type ALRT 
40 40 130 472 ,900 
Visible 1 NoGoAway 0 40 80 200 432 
900 10822 
New Dialog 4444 
Type PICT 
,901 
Type DITL x No format specification available. 
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Forth Forum 


Batch Text File Transfer bp XMODEM 


If you don't happen to have a tape backup unit for your 
Macintosh, but access to some larger computer installation 
over a terminal line (with, usually, lots of disk space), there is 
a slow but secure way to keep backups of your files by 
uploading them to that machine. There are all sorts of 
communication utilities that help in doing so, most of them 
using the XMODEM protocol for up- and downloading files. 

The telecommunications programs I am aware of at this 
moment are excellent tools for transferring single files to and 
from the Macintosh. If one wants to back up one full disk by 
such a file transfer, however, the task becomes a little tedious 
since one has to select one file at a time; particularly time- 
consuming if your disk has 327 short text files on it. The 
XMODEM standard does offer a batch transfer mode in which 
the filename is transferred followed by the file, and if anyone 
out there knows of a terminal program that has this mode 
implemented, please let me know. 

For the time being, the transfer of one whole volume on 
a HFS disk from the Mac to another system by XMODEM 
batch transfer is a neat little project to implement in Forth. 
Besides being useful, it'll help us gain some insight into HFS 
file handling. 

We will limit ourselves to transferring text files here. 
Since you all are aware that files on the Macintosh consist of 
the data and the resource fork, applications and other resource- 
containing files have to be changed into text files using a 
utility like BINHEX first. However based on our example, it 
is rather easy to implement the MacBinary format [a special 
standard combining both forks together with the Finder 
information into one structure: see MacTutor V2#1], and 
transfer files of any type automatically. At the present time, a 
text file backup system is fine for me, since the documents I 
most often have to back up, like manuscripts or current 
versions of Mach 2 and NEON source files, are text files 
anyway. 

The XMODEM Batch Transfer Protocol 

How does an XMODEM file transfer proceed? Each file is 
split up into sectors of 128 bytes each (a relic of old CP/M 
times), each sector starting at one. A simple file transfer (not 
batch mode) has the following protocol: 

Simple File Transfer Protocol 
Receiver 


Sender 


waits for NAK, 
80 sec timeout sends NAK at 
18 sec intervals 
Loop n times for n sectors 
send header : 
SOH ($81) 
sector no. (0-255) 
sector no. complement (255-0) 


send sector data, 128 bytes 
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send checksum: 
Cheader bytes + sector data ) mod 255 


compute checksum and 
compare with checksum 


byte 
send ACK ($06) if OK and 
NAK if not 
If ACK received, increment 
sector no. 
otherwise resend sector 
End Loop 
send EOT ($04) 
send ACK 


The transfer may be cancelled at any time by the sender or 
receiver transmitting a Ctrl-X ($24) to the other end. 

In batch mode, there is an additional protocol defined to 
transmit the filename before the file transfer starts: 


Batch Mode Protocol 
Sender Receiver 
waits for NAK, 
80 sec timeout sends NAK at 
18 sec intervals 
sends ACK 
awaits filename characters, 
1 sec timeout 
on error -? above NAK 
Loop 11 times 
send filename char 
(bit 7-20, upper case) 
add to checksum receive filename char 
await ACK 1 sec timeout add to checksum 


ACK 
End Loop 
send Ctr1-Z 
add to checksum receive Ctr1-Z 
add to checksum 
send checksum 
receive checksum + 
verify 
ACK if OK and "u" if not await ACK 


- Normal file transfer starts - 


NAK 
SOH 
EOT 

ACK 
expect NAK to start new 
filename NAK 


ACK for new file name 
or EOT if finished 

The routines necessary to implement this protocol are 
printed in Listing 1. [For the single file transfer protocol, I 
adapted some routines from an article by Robert Taylor in Dr. 
Dobbs Journal 83 (9/1983) p.66.] 

The program in Listing 1 is best used by having some 
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terminal emulation like Mockterminal running on the 
Macintosh at the same time. Mach2 users may append this 
code directly to the "Terminal Emulator" example on the 
Mach2 demo disk and then start the terminal emulator before 
doing the transfer. For other Forths, the program should be 
easily adaptable, you'll have to change the routines for setting 
the baud rate and for doing the modem input and output. 

Look at the definition of the words send and send- 
filename and the inner loop of send for the implementation 
of the XMODEM protocol in Forth. 

In order to be able to transfer one whole volume 
automatically, we must have some means for accessing the 
files on a volume one by one. The example contains some 
file and directory handling words for this purpose. I have also 
left in there some words I needed in testing (like $openWD) 
which are not used in the actual implementation, but could be 
useful at times. 

The Mach2 word $open opens a file on the default 
volume, given a name string, and returns a file ID number. In 
order to access files in any arbitrary folder (= HFS volume), 
we have to get a volume ID number first and set the default 
volume to this ID. The word promptvolID calls the 
standard file package to prompt the user to select a file in the 
folder that is to be transferred. Then the volume ID of this 
folder is returned. Calling setvol with a volume ID sets the 
default volume. getidxfile takes as its input a volume ID 
and an index n and will look for the n-th file in the volume. 
The filename is returned in a global parameter block, 
parblock, and can be used to open the file with $open after 
setting the correct default volume. send-batch simply scans 
the default volume for all files and transfers them one by one. 
So far, for text files only. Have fun implementing the 
MacBinary standard. 

Reader Feedback 

I got several comments on the floating point routines 
that we published lately. Ed Moskowitz from Winfield, IL 
points out correctly that the routines will not work with the 
new Mach? since they use D5 and D6. This is correct, and D5 
and D6 have to be added to the MOVEM.L save and restore 
list at the routine entry and exits to fix this bug. 

Mike Morton from Cambridge, MA had some useful 
comments to make about improving the speed of those 
routines. Excerpts from his letter: 

"e If you're doing lots of  Pack4 calls, you can do a 
GetTrapAddress and call the package directly, saving 30 to 50 
microseconds (...) 

e Instead of BTST #7, DO, you can do TST.B DO 
and use BMI to see if the bit is on. 


e ...when you AND #$7FFFFF to both D3 and D1 in 
the division routine, it's faster to move the mask to a register 
Just once and use it twice. (...) 

* When you're doing multiplications [and divisions, JL], 
you might optimize for cases where some of the number is 
zero. So your four MULUS might test whether the operands 
are zero and handle that case explicitly. I spent some time 
writing 32-bit fixed-point multiply routines a while ago, and 
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this helped a lot because many numbers don't have any bits on 
the bottom of the longword. If you expect many of the f.p. 
numbers to not have many significant bits, this helps some. 

Gae 

Thanks, Ed and Mike, for your comments. 

NEON News 

One letter came clear from Tasmania, from Phil Barnard: 

"...I am suffering from the new ROM syndrome at the 
moment, although the faster and more spacious drives are very 
pleasant after the original units. Having to replace the 
interrupt vectors for the interrupt button was a nuisance. As 
you are no doubt aware the new ROM/System does not 
present the familiar bomb-box, but an 'empty' dialog. 

It may be that the new dialog can be used to resume in 
the same fashion as the old one, but I don't yet know how. G 
«return» sends it back into any loop that you may wish to 
exit. Looking at the register contents by typing AO through 
D7 is of limited debugging use. Can it do anything else?" 

[Why, I even installed a control panel with flashing 

LEDs and toggle switches on the top of my Mac. Why do you 
want anything else? ... Well, G 40F6D8, of course, you 
probably know by now that that is the address of Exittoshell 
and will (sometimes) send you straight back to the Finder. I 
don't use it for many other things. JL] 

"The following routine brings back the old familiar bomb- 
box on interrupt." 


\ installation of custom interrupt vectors; Phil Barnard 
V ** INTERRUPT VECTORS ** 

V prints out the seven vectors from the interrupt table 
; get. ints C -- ) cr 


$ 64 -base @ . cr V VIA 
$ 68 -base 6 . cr \ SCC 
$ 6C -base 8 . cr V VIA & SCC 


\ Debugging Button 


> 
~J 
oo 
l 
c 
Q 
” 
[17] 
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O 
^73 
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$ 7C -base @ . cr 

CREATE RTS $ 4ET75 NEXT, 

V installs RTS in the last four (debugging) vectors in the 

interrupt table 

: put. ints € -- ) 

$ 80 $ 70 do 'c RTS *base i -base ! 4 *loop get.ints ; 
Thanks, Phil. I'll deal with more NEON stuff in the next 
column where I'll also have some time to write about the new 
release of NEON, version 2.0. Here only a few headlines: 

* NEON 2.0 is fully HFS and Switcher compatible; a new 
class pathlist has been added to specify HFS search 
paths. The assembler supports the new ROM calls. 

* Applications install as a one piece file, no need to keep a 
copy of the installed NEON kernel on the disk. 

* À decompiler has been added that will handle simple 
definitions, classes, objects and methods. 

* À number of bugs, including the famous IC! have been 
fixed. 

More details about NEON 2.0 and other NEON things 
later. Till then, good holidays. 

Listing 1: XMODEM batch file domloader 

( Implementation of Modem? file transfer protocol, 

€ 9/86 J. Langowski for MacTutor ) 

only forth also mac also i/o also assembler 

decimal 


68 user fileID 


10 constant maxerr Ø constant nul 24 constant can 
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4 constant eot 6 constant ack 21 constant nak 12 1 do filename i + 


1 constant soh 26 constant ctr1-z c@ 127 and dup 95 » if 32 - then 
117 constant bdnmch dup modout dup emit 
cksum cê + cksum c! 
" Select file on volume to upload:" constant seldirtext wait-ack 
loop cr 
variable time-ct variable nak-ct variable cksum ctr1-z modout 
cksum c8 ctrl-z + cksum c! 
variable filename 128 vallot j 
variable xbuffer 128 vallot 
variable replyrecord 74 vallot : send-hdr ( sector | -- } 
soh modout 
header parblock 12 allot € 12 bytes junk ) sector" 1+ 255 and dup modout 255 xor modout 
header iocomp] 4 allot C at PB + 12 D ." Sending " sector? . cr 
header iores 8 allot C at PB + 16 ) ; 
header ioref# 4 allot C at PB + 24 D 
header iomisc 4 allot C at PB + 28 ) : send-sect ( send sector in xbuffer via XMODEM ) 
190 allot C some elbow room ) Ø C sum ) 
128 Ø do xbuffer i + cê dup modout + 255 and loop 
: long-timeout 1008 time-ct ! ; ( 17 sec timeout ) cksum c! 
: Short-timeout 100 time-ct ! ; € 1.7 sec timeout ) F 
: baud-rate ( - ) : send-cksum cksum c@ modout ; 
1CCBA COMM1 mode € 9600 BAUD Xon/Xoff ) 
ABORT" Serial Driver Error" ; (8 bit, No Par, 2Stop) : end-send 
close-file 
: modout commi output emit console output ; begin cr ." Sending EOT -" eot modout wait-ack 
: fin cen modout ; : fini fin close-f ile ; n&k-ct 8 B= until 
." eck'd" 
: timed-read ( | tstart -- char ) j 
call tickcount -> tstart 
commi input : get-file-length ( -- sectors ) 
begin fileID wê [') ioreftt w! 9 ['] iocompl ! 
?terminal if key console input exit then ['] perblock call geteof . cr 
call tickcount tstart - time-ct @> ['] iomisc @ 128 /mod swap 
until if 1+ then 
console input -1 dup ." File hes " . ." sectors" cr 
, ) 
: Icontrix ?terminal : send ( current file via XMODEM, closes file on exit ) 
if key 24 = get-file-length 8 
if fini 1 abort" Control-X abort" then do 
then begin 
E i read-sect ( into xbuffer ) 
i send-hdr send-sect send-cksum 
: wait-ack ( | errs -- ) wait-ack nak-ct @ d= 
ð -> errs until 
begin errs maxerr ? nak-ct 6 maxerr ? or 100p 
if fini 1 abort" Max error count exceeded." then end-send 
?contr 1x i 
timed-read case 
-1 of errs 1+ -> errs ." Timeout" cr endof : prelude 
cen of 1 abort" Remote Cancel" endof short-timeout begin timed-read -1 = until 
ack of Ø nak-ct ! exit endof long-timeout ." Awaiting initial NAK: " 
nak of 1 nek-ct +! exit endof wait-ack cr short-timeout 
( disp-chr Ø ) ; 
endcase 
egain : send-one send-setup prelude send ; 
: end-batch ack modout eot modout ; 
: send-setup 
long-timeout ( *** file and directory hendling routines *** ) 
stenderd-getfile = 
if fin 1 abort" Cancelled." then : getVolID ( index | pb -- VRefNum / errcode 0 ) 
Ø nak-ct ! (C ID for volume no. index ) 
: ['] parblock -> pb 
9 ['] iocompl ! 
: read-sect ( sector® | sect-stert -- ) filename pb 18 * ! 
sector? 128 * -> sect-stert index pb 28 * w! 
128 0 pb call getvolinfo 
do i sect-start + virtual c8 i xbuffer + c! loop ?dup if Ø else pb 22 + wê then 
J s 
: send-f i lename CODE SFGetFile € x y prompt numTypes typeList ReplyRecord ) 
ack modout Ø cksum c! MOVE .L (A62*,A1 ( reply record ) 


460 O The Complete MacTutor, Vol. 2 


type list ) 


MOVE .L (A62*,A0 ( filename pb 18 + | C ioNamePtr ) 
MOVE.L (A6)*,D3 ( numTypes ) volume pb 22 * w! € ioVRefNum ) 
MOVE .L (A62*,02 C prompt ) Ø pb 26 +w! € ioFVersNum ) 
MOVE.L (A62*,D1 C y-coord ) index pb 28 + w! € ioFDirIndex ) 
MOVE.L CA6)+, DØ ( x-coord ) pb call getfileinfo 
dup 0- if ." Found: " filename count type cr then 
MOVE.W — D0,-CATD ; 
MOVE.W D1,-CA7) ( where ) 
MOVE.L — D2,-CADD ( prompt ) : openidxf ile ( volume index | -- res code ) 
MOVE.L — 80,-CA7D ( no filter proc ) volume index getidxfile 
MOVE.W — D3,-CADD ( num Types ) ?dup Ø= if filename $open then 
MOVE.L — A0,-CA7D ( type list ) f 
MOVE .L 89, -CAT) C no dialog hook ) 
MOVE.L A1,-CA7) C reply record ) : find-files ( | volume index -- ) 
promptvolID 
MOVE .W 82, -CAT) if -> volume 1 -> index 
-Pack3 begin 
RTS volume index getidxf ile 
END-CODE index 1* -> index 
until 
: promptvolID € -- VRefNum flag ) else ." cancelled" . cr 


4 


108 50 seldirtext -1 Ø replyrecord 


SFGetfile 


replyrecord 6 + we 1 ext 
replyrecord wê l_ext 


then 


( *** main definitions for batch file transfer *** ) 
: display-filename 

12 1 do filename i + c@ 127 and dup 95 » if 32 - then 
enit 


CODE SFPutF ile loop cr 
MOVE.L — CA0*,A1 : 
MOVE.L — (A60*,40 : send-batch ( volume | index ) 
MOVE.L (A62*,D3 1 -> index Ø nek-ct ! 
MOVE.L (A62*,D2 begin cr 
MOVE.L (A62*,D1 filename 1+ 11 32 fill 
MOVE.L (A62*,D0 volume index getidxfile Ø= 
while 
MOVE.W — D0,-CATD volume setvol drop 
MOVE.W D1,-CA7) filename $open dup Ø> 
MOVE.L — D2,-CADD if fileID w! 
MOVE.L — D3,-CADD begin 
MOVE.L A@,-CAT) prelude send-f ilename 
MOVE.L A1,-CA7) timed-read cksum c8 o 
while 
MOVE.W %1,-CA7) ." Checksum Error in filename, 
-Peck3 resterting" cr 
RTS bdnmch modout 
END-CODE repeat 
ack modout 
: $openWD ( name | pb -- VRefNum / errcode Ø ) send ( closes file ) 
['] parblock -> pb else drop 
Ø ['] iocompl |! then 
name pb 18 * ! index 1* -> index 
Ø pb 28 + w! repeat 


pb 1 call HFSDispatch 


?dup if Ø else pb 22 + w@ then 


: closeWD ( volume | pb -- rescode ) 


['] parblock -> pb 


Ø ['] iocomp] ! 
volume pb 22 * w! 


wait-ack end-batch 


: upload 
promptvolID 
if send-batch 
else cr ." Cencelled" cr 
then 


pb 2 call HFSDispatch 


: setVol ( volume | pb -- res code ) 
['] parblock -> pb 
Ø ['] iocomp] ! 
Ø pb 18 + | 
volume pb 22 + w! 
pb call setVol 
: getidxfile ( volume index | pb -- res code } 
['] parblock -> pb = 


['] iocomp] ! e«t 


O The Complete MacTutor, Vol. 2 461 


Fortran's World 


REdit 
ResEdit 1.0d7 


462 © The Complete MacTutor, Vol. 2 


Fortran's World 


Attaching Assembly Routines to Fortran 


This month's column will cover several diverse topics 
that have a common underlying theme: increased access to the 
toolbox and an introduction to integrating assembly language 
subroutines. However, before undertaking the new topics 
several additional items need to be noted concerning the new 
Microsoft version of MacFortran. 

First, the Microsoft version of MacFortran is on the 
Streets (2.1 of the Absoft version). This is not entirely news 
since both the October and November issues used the 2.1 
version. However, for those of you who have not upgraded 
yet from 2.0, the new version has different parameter equates 
for the subroutine toolbx. The 2.0 version uses decimal 
numbers for the parameters and the new 2.1 version uses hex 
and the two do not match. So, if you are trying to run a 
program written in the other version, watch those parameter 
definitions in calls to the subroutine toolbx. 

Second, the 2.1 version does make life somewhat easier 
in setting up the parameter definitions for the subroutine 
toolbx by providing a set of text files grouped by areas of the 
toolbox, i.e., event manager, window manager. These text 
files can be included in the main file, relieving the drudgery of 
typing all that information in over and over. However, beware 
of the event.inc file. This text file also contains a variable 
definition for the array variable eventrecord and equivalence 
statements to variables identifying specific elements of 
eventrecord in addition to the toolbx parameter definitions. 
Inclusion of the variable eventrecord and its equivalenced 
variables in this file means that every program segment in 
which you include event.inc knows those variables. Now 
consider the following situation, the main program contains 


Program Main 
include event.inc 


call menus(where) 


and the subroutine is defined as 
subroutine menus(where) 


include event.inc 


In this situation the compiler will generate an error, 
apparently due to the equivalenced variables. The best way to 
avoid this problem is to remove the eventrecord variable 
definition and the equivalences from the event.inc file (I put it 
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in a separate file) and explicitly declare an event record type of 
variable in each program segment that needs it. It's odd, but 
the event.inc file was the only file of the ones provided by 
Microsoft that contained both a variable definiton for a Mac 
record structure and the parameter definitions for the toolbx 
subroutine. 

Third, the upgrade for the new version for existing 2.0 
owners will cost $100 which I believe is steep. Given the 
limited new features (DO WHILE, a few new compiler 
options, increased access to the toolbox, and a completely 
rewritten linker) and that I would consider the last two in that 
list as fixes to existing problems, I was taken aback by the 
price. In addition, my understanding of Microsoft's Tequire 
everything of you and promise nothing in return licensing 
agreement’ is that it does not allow you to distribute 
programs which are standalone applications: compiled and 
completely linked code which includes the runtime library. I 
talked to Microsoft about the latter of these two issues. The 
reply was that in order to include the runtime in a compiled 
application code you distribute (commercially or via public 
domain) you need to execute a second agreement with 
Microsoft. This second agreement gives you the right to use 
the runtime in application packages and evidently does not 
cause you to pay royalties (but I am not positive that it is 
royalty free, I am trying to get official word on royalties). 
Microsoft said to contact the Legal department of Microsoft 
for further information on this additional licensing agreement. 
Iam requesting a copy of the agreement and will report on my 
experience in a future column. (What nonsense! -Ed.] 


Using Assembly Subroutines 


Assembly language subroutines can improve your 
Fortran program in two ways. First, for those subroutines in 
applications where speed is critical, a tightly coded assembly 
subroutine may outperform the code of the compiler. The 
gain from this approach may be minimal since the compiler 
produces fairly tight code. Second, shortcomings in the access 
to the toolbox routines can be addressed through assembly 
language subroutines. For example, in November's shell 
application, a modaldialog box was used in the ‘About this 
program’ menu choice in the desk accessory menu. The dialog 
box used the default userfilter function provided in the toolbox 
because of MS Fortran's inability to handle user written 
Fortran filter functions. Conversations with Absoft indicate 
that given the incompatable use of CPU registers between 
MacFortran and the Mac, user filter functions are probably 
best written in assembly. The number of tricks necessary to 
write the filter function in Fortran will be large and probably 
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more difficult to implement than just writing the filter 
function in assembly. 

The example program provided below illustrates a simple 
call to the toolbox routine MODALDIALOG via an assembly 
language subroutine. If a special user supplied filter function 
is required, it can be coded in assembly and integrated with the 
assembly program presented in Listing 1. The subroutine is 
called from Fortran with a ‘Call Mdlg(dnum,itm)' 
statement where dnum is the dialog box resource number as an 
integer*2 and itm is the dialog item to check for as an 
integer*2. This assembly subroutine, thus, does not do 
anything particularly overwhelming. However, it does 
illustrate several items about accessing assembly subroutines 
from Fortran; including how to pass values to the assembly 
subroutine. Listing 1 is given in MacAsm format and would 
require a few modifications for the MDS system (see 
MacTutor Vol 1 No. 9 page 20 for the synatx differences 
between MacAsm and MDS). 

The first few lines set up the MacAsm environment. The 

include files define the macros for TBX, OST, and DC 
directives and are stripped down versions of the file 
‘Library.Asm’ provided on the MacAsm program disk. The 
equates define the toolbox trap values for the routines that will 
be called by this subroutine. Notice that none of the 
intialization routines (TEINIT, etc.) need to be called because 
they will have been previously called by the MS Fortran 
system. The Tfile directive gives the name of the file to store 
the compiled object code in. The compiled code is relocatable, 
so for convenience the origin will be set at address 
$00000000. 
The next block of lines define the local dynamic storage 
for the subroutine and set up the ability to get the values 
passed to and from the assembly subroutine. Upon entry to 
the subroutine, MacFortran has pushed the following onto the 
stack (the top item listed is the first item on the stack) which 
is referenced off register A7 - 


RTS - calling procedures return address 
an - address of nth argument in items passed 


a2 - address of 2nd argument in items passed 
a1 - address of 1st argument in items passed 
s1 - length of 1st item passed 

s2 - length of 2nd item passed 


sn - length of nth item passed 


Memory Location 


Previous stack contents 


159EC | 00015A04 address of dnum variable 


159E8 | 00015A06 address of itm variable 
(SP)-> 159E4 | 000064C6 return address from subroutine 


Low Memory 
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Character items have their length passed, numeric items 
do not. Constants which are passed are copied to a memory 
location and the address of the memory location is passed. A 
pointer to the stack memory location which contains the 
addresses of the first variable passed is put in register A3 in 
line 190. Variable offsets relative to A3 are defined in lines 
120 and 130. This will let us access the items passed later in 
the program. Figure 1 illustrates the contents of the stack 
upon entry to Mdlg.sub as executed in a test program. 

In addition to the items on the stack, the following 
information is contained in the registers of the CPU 


AO : pointer to communications area 

A4 : pointer to MacFortran library jump table 
A5 : pointer to MacFortran work stack !! 

A6 : pointer to stack frame 

DO : the number of arguments passed. 


Label "Start" simply checks DO to see if the proper 
number of variables has been passed, exiting the routine if 
they have not. Only one local variable will be needed, 
ITMHT, which is two bytes long. If a second local variable 
of 4 bytes, called COUNT, was needed it would be handled 
with the following statement COUNT equ ITMHT-4' in the 
equates portion of the program. When combined with the 
LINK statement, a local dynamic variable area indexed off 
register A6 is set up on the stack in a data structure known as 
a stack frame. MS Fortran depends heavily on stack frame 
constructs for passing arguments and it is critical that you 
maintain the integrity of the A6 register. 

Next we save all the registers except A6 & A7 onto the 
stack (indexed off the stack pointer, A7). MS Fortran uses the 
AS register extensively for a work stack. So does the Mac. 
MacFortran resolves the conflict by relocating the Mac 
pointer! Thus, to be able to use the Mac pointer, we must 
restore it to the AS register, in the line with the comment 
Testore quickdraw globals' Figure 2 illustrates the stack after 
execution of the link statement and the save registers 
Statement at the beginning of the routine. At Exit, we 
restore all the registers to their initial values when the 
subroutine finishes. Be sure that your subroutine hasn't left 
any stray items on the stack before restoring. Finally, we 
unlink the dynamic storage return to the Fortran program. 
This sequence of tag the location of the addresses of variables 
passed, LINK local dynamic storage, save the world (except 
A6 & AT), move the Mac pointer back to A5, restore the 
world (except A6 & A7), and UNLINK will allow you to 
successfuly setup and maintain local dynamic storage, pass 
values back and forth to Fortran, and use the AS register as the 
Mac developers intended you to. 

As you saw, Fortran passes arguments to subroutines by 
addresses on the stack. Values can be returned to the variables 
used in the call to the subroutine via these same addresses. 
External functions return their values in registers DO and D1 
(address in Al for character functions). See the examples 
discussed in Appendix E of the manual for further aspects of 
passing arguments. 
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Memory Location 


0000 B054 saved value of A5 register 
saved values of registers 


0000 0002 saved value of DO register 


Fig. 2 


Finally, we can establish our modal dialog box by 
getting it from the resource fork and then use the toolbox trap 
MODALDIALOG with the default userfilter function to handle 
interaction with the modaldialog box. Notice how we get the 
value of dnum for the call to modaldialog. Dnum's address 
was passed to the subroutine via the stack. Refering to fig. 1, 
we load the address of dnum to register A1 with the pointer we 
saved in A3 and an offset. Then just prior to label ".0", we 
use indirect addressing off A1 to push the value of dnum onto 
the stack. This trick is also used to retrieve the value of itm 
for comparison to the item number clicked by the user prior to 
Exit. If the item number 'hit' by the user matches with the 
itm value passed from the Mdlg call, the routine exits, 
otherwise it retruns for another call to modaldialog. Before 
leaving, we close the dialog window. 

Introduction of a user written filter function in assembly 
could now be accomplished. Label ".0" passes the effective 
address of the filter function. If a null value is passed, as is in 
Listing 1, the Mac supplied default filter function gets used. 
However, changing this CLR.L -(SP) to PEA (Myfilter,PC) 
allows the assembly coded filter function located at Myfilter to 
be used. The relative addressing off of the program counter is 
necessary to maintain code position independence. Given the 
memory management of the Mac, we must also lock the 
subroutine in memory, so that the absolute address passed in 
the PEA instruction remains correct even during the call to 
modaldialog. Conversations with Absoft revealed that you can 
lock an external assembly language subroutine by using the 
command 'MOVE.W #1,-8(A1)'. This pushes an immediate 
I into the proper place to lock the subroutine. This should be 
done before any of the registers (notably A1!) are modified by 
your subroutine. At the start of the program (between lines 


High Memory 


(A3)-> 159EC 


159E8 


159E4 


(A6)-> 159E0 


159DE 


159DA 


(SP) 159A6 


Low Memory 


© The Complete MacTutor, Vol. 2 


160 and 170 in Listing 1) would be a good choice. Notice 
that the subroutine will remain locked in memory for the 
duration of the Fortran program. 

Assembling the program in Listing 1 under MacAsm 
generates a relocateable object code file that cannot be used 
with the MS Fortran linker. The MDS system will generate a 
compatible file that can be used with MS Fortran if the code 
file is put in the data fork. [This can be done by assembling 
the file with MDS, linking it with itself with MDS to create a 
code resource, and then using FEdit to swap it from the 
resource fork to the data fork. Then strip the 121 byte header 
from the file so the first byte is the first program byte, or 
insert a jump instruction at the top of the file. -Ed] The 
difference lies in that MacAsm tags two 32 bit addresses onto 
the start of the file as load information for the MacAsm linker. 
Stripping these bytes provides the second example program for 
this month's column. Once the extra bytes generated by 
MacAsm are stripped, the modaldialog can be used simply by 
calling the subroutine. For example, in November's shell 
program the revised section of the code would be: 


case(Apple) | "Apple" menu selected 
menuhandle=toolbx(GETMHANDLE, Apple) ! get "Apple" 
select case(menuselection(2)) ! "Apple" menuitem 
case(About) ! About item selected 
dnum=200 
itemnum=3 
call Mdig(dnum, itm) 
case default ! Desk Acc. selected 
Call toolbx(GETITEM,menuhandle, item4,name) 
refnum=toolbx(OPENDSKACC, name) 
end select 


As long as the assembled object code file is on the disk 
with the name Mdlg.sub (6 or less characters, not counting the 
.Sub!!!), the shell program will use the external assembly 
subroutine. ^ Further, the external assembly language 
subroutine can be linked to the application code with the MS 
Fortran linker. 


File Handling in MS Fortran 


The need to strip the header bytes from the MacAsm 
object file provided a perfect opportunity to explore the 
standard getfile and putfile routines in the Mac. MS Fortran 
makes the job much easier by providing a general purpose 
function, stdfil, on the source disks included with version 2.1. 
The calling sequence is: 


stdfil(what, prompt, file, n, types) 
where the input arguments are 
what: O=SPUTFILE and 1=SFGETFILE 
prompt: prompt string for SFPUTFILE 


file: default file name for SFPUTFILE 
n: number of ‘types’ 
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type: character*4 array of file type filters 


and the output arguments are 


file: file name as "Volume filename” 
stdfil: true if ‘file’ is valid. 


The short program given in Listing 2 provides an 
example of using stdfil to open a file, strip the MacAsm 
header bytes, and save the new file. Examining the code 
illustrates how stdfil can be used to make the file 
preconnections that Fortran requires. 

The stripper program first removes the default MS 
Fortran window and then opens a new window using a toolbx 
call to NEWWINDOW and sets the current grafport using 
SETPORT. Next the program sets the textfont and size using 
toolbox calls. The last call, to the toolbox routine 
GETFONTINFO, returns the font characteristics in the font 
information record, fontinfo. This gives us information about 
the font which is useful in spacing our displays. 

Figure 3, a variation on the diagram given in Font 


ascent line 
font base line 
size 
descent line 
> leading 


Fig. 3 

Manager section of Inside Mac, shows the interpretation of 
these characterisitics. Ascent is the distance from the base line 
of the font to the top of font. Descent is the distance from the 
base line of the font to the bottom of the font. Widmax is the 
greatest distance the pen will move when a character in the 
font is drawn. Finally, leading is the vertical distance between 
the descent line and the ascent line of the line below it. Thus, 
the height of a character can be interpreted as the sum of the 
ascent, the descent, and the leading or the distance from the 
ascent of one character and the ascent of the character on the 
line below. 

After getting the font information, the program uses a 
call to stdfil to get the name of the file to be opened and 
stripped, as shown in Figure 4. Notice that stdfil will select 
only those files of type "YBIN' which is the MacAsm tag and 


TETTE sub 


m 


the selected file name will be returned in the character*64 


variable ofile. The program then opens unit 10 as the 
sequential unformatted file. If stdfil returns false (e.g. cancel 
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button pushed) the program skips to printing the final screen. 

After opening the file to be stripped, the program uses 
stdfil to retreive the output file name from the user, see. The 
output file is assigned to unit 11 as a sequential 
unformatted file. 

Once both input and output files have been opened, the 
program loops through the file one byte at a time, outputting 
the bytes after the header information has been passed. Notice 
that the font information is used to control the printing of the 
hex bytes, particularly to space between the lines. The 'type' 
statement is used instead of 'write' so that the font selected 
will be used to print on the screen. 

When the entire file has been read, the program exits to 
short program segment which draws a box around those bytes 
stripped from the file and displays information on the screen 
about the file selected and outputted. Again, the font 


Stripper 


[0000 0000 0000 003C] 4E56 FFFE 48E7 FFFC The boxed values have been 
2868 FFFC 4287 3F3C 00C8 42A7 2F3C FFFF stripped from the file 
FFFF AOTC 2E1F 4287 486E FFFE A991 300E McBride:Mdialog.sub 
FFFE 0C40 0003 66EE 2F07 A982 4CDF 3FFF 


4ESE 4E79 and stored in the file 
HcBr ide:lldlg.sub 
Fig. 5 h 
Press return to continue. 


characteristics are used to space out the display, as shown in 
Figure 5. 

Use of the toolbx routines SFGETFILE and SFPUTFILE 
are relatively easy given the MS Fortran supplied subroutine 
stdfil. Studying the source code for stdfil can give you ideas 
about how to improve the handling of the filenames with 
SFGETFILE and SFPUTFILE. 


Accessing Mac Global Variables 


The final topic for this month's column deals with 
accessing Mac global variables which are discussed in the 
Quickdraw Programmers Guide portion of Inside Mac. Why 
would you care about accessing these globals from Fortran? 
Well, in the original September 1985 column I discussed that 
in Version 2.0 you could not use the toolbox random number 
generator because you had no way to seed the generator. The 
random seed is located as a global variable index off register 
AS. Version 2.1 will let you access those global variables. 
Also note that in the October fractuals program, the call to 
toolbx{RANDOM) will always generate the same random 
sequence because the intialization of quckdraw by the toolbox 
sets the seed to 0 and the fractuals Fortran program has not 
reset the seed. 

Accessing the Mac global variables is done through a 
toolbx subroutine call to GETGLOBAL with an offset to the 
particular global variable desired. These offsets are not 
included on the MacFortran diskettes. Absoft graciously 
provided me with a copy of a file they call aSglob.inc which 
has been reprinted in Listing 3. This include file defines the 
offsets for the global variables. Now, if we wish to get a 
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pointer to the random number seed location, we just need to 


use ' 


toolbx(GETGLOBAL)+RANDSEED". We then can use 


this pointer with the LONG function to read or modify the 
value of the random seed. The following short program will 
generates a different random sequence each time run by 
reseeding the toolbox random number generator with the 


System tickcount. 


Note the the toolbox random number 


generator returns an integer value between -32768 and 32767. 
program random test 


integer*4 i, toolbx 

include quickdraw. inc 

include a5glob. inc 

include misc. inc 

include event.inc 
longCtoolbxCGETGLOBAL )*RANDSEED) 


-toolbxCTICKCOUNT ) 
do (i=1,25) 
writeC6,*) toolbxCRANDOM) 
repeat 
end 
This ends our exploration this month of the world of 
MacFortran. 
A 
Listing 1 
; SAVE"Mdialog. Asm" 
K = mæ lll 
LIST OFF 
INCLUDE "ShortLibrary.Asm" 
INCLUDE "DCs.Asm" 
Xone 
GetNewDialog equ $497C 
CloseDialog equ $4982 
ModalDialog equ $4991 
ITMHT equ -2 
NARG equ 2 
DNUM equ 9 
ITM equ DNUM-4 
LIST ON 
TFILE — "Mdialog.sub" 
fone we mme cm 
START — CMP.L — *"NARG,D0 ;check for number of args 
BNE NOARG ;wrong number of arguments 
LEA NARG*4CAT),A3  ;point at lest argument 
LINK A6, *t ITMHT ,get local storage 
MOVEM.L A0-A5/D00-D7,-CSP) ;save the world 
MOVE.L -4CA0), A5 ,restore quickdraw globals 
CLR.L -(SP) returned hande 
MOVE.L DNUMCA32,A1 ,get dnum address 
MOVE .W (A12, -CSP) ;put dnum to stack 
CLR.L -(SP) ,Store on heap 
MOVE.L 8-],-CSP) jin front 
TBX GetNewDialog ,get new dialog 
MOVE.L (SP2*,D7 ,save handle 
Ø CLR.L -(SP) ,use default filterproc 
PEA ITMHTCA6) ,Storage for item hit result 
TBX ModalDialog ,call modaldialog routine 
MOVE .W ITMHTCA62, DØ ,get item hit result 
MOVE.L ITMCA3),A1 ,get item number to check 
CMP .W (A12,D0 ,8nd compare to item result 
BNE.S .e ,do it again if not 'ok' 
MOVE.L D7,-CSP) ;push dialog handle on stack 
TBX CloseDialog ,close dialog window 
Exit MOVEM.L (SP)*,A0-A5/D0-D7 ;restore the world 
UNLK A6 ,deallocate local storage 
NOARG RTS 
Rae i oa oe eee wee ee Se ad eur 
END 
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Listing 2 


x 
x 
x 
x 
C 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 
x 


The following program strips the first 8 bytes (two 32 bit 
words) from the start of a MacAsm binary file. Thus, the 
program can be dangerous. Its intended use is to Strip off 
the bytes placed at the start of a MacAsm object file 
reated 
using either the TFILE or BSAVE commands. MacAsm uses 
these two 32 bit words as load information. 
The progrem is written for the MS Fortran V2.1 compiler and 
makes use of a subroutine Stdf il developed by 
Microsoft/Absoft. 
Mark E. McBride 
211 N. University Ave. 
Oxford, OH 45056 
(513) 523-1438 


Program Stripper 


implicit none !keeps us out of trouble 
include window. inc 

include dialog. inc 

include quickdraw. inc 

include misc.inc 


integer*2 word 
logical stdf il 


8 two byte word 
! external get and put file 


routine 


character*64 ofile,nfile ! old file name and new file 


name 


character*256 strg general purpose string 


variable 


x 
x 


call toolbxCTEXTFONT, 4) 


integer*2 rect(4) 
integer*4 i 


! general purpose rectangle info 

| 
integer*4 toolbx ! 

! 

| 


looping variable 
toolbox interface 
integer*4 window, ow general purpose wind. handles 
integer*1 o. record( 154) window record 

integer*2 fontinfo(4) ! font information record 
integer*2 ascent, descent ,widmax, leading ! font style 
integer*2 height ! height from top of font to top 
integer*4 normal,bold ! textface styles 


equivalenceCfontinfoC 1), ascent) 

equivalence(fontinfo(2), descent) 
equivalenceCfontinfoC3),widmax) 

equivalence(fontinfo(4), leading) 
data normal,bold /@, 1/ 


Close MacFortran I/0 window 


window-toolbxCFRONTWINDOW) 
call toolbxCCLOSEWINDOW, window) 


Open viewing windows 


rect(C 12-58 

rect(2)-20 

rect(3)2350 

rect(4)-500 
Strg=char(len(trim("Stripper")))//"Stripper" 
ow=toolbx(PTR, o_record) 

ow=toolbx(NEWWINDOW, ow,rect,strg, .true.,4,-1,.false.,@) 
call toolbxCSETPORT, ow) 


Set textfont and size 

! monaco font 
call toolbxCTEXTSIZE,9) ! 9 point 

call toolbxCTEXTFACE, normal)! normal 

call toolbxCMOVETO,20,20)  ! move to start point of text 
call toolbxCGETFONTINFO, font info) ! get font stuff 
height-ascent*descent* leading 
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* Get input and output file names and process 
x 


if (stdfilC1,' ',ofile,1, YBIN')) then 
openC 10, f ilezofile,access-'sequential',form-'unformatted') 
nfilez"untitled" 
if Cstdf ilCO, ‘Save File Name',nf ile, 1, ''D)) then 
open( 11, file=nfile,status='new',form='unformatted', 
+ access-'sequential') 
x 


* loop through the file a byte at a time 
x 


i=! 
do 
read( 19,end=188) word 
if (i»4) writeC11) word 
type 1099,word,' ' 
1000 + format(z4.4,a1) 
call toolbxCMOVE, widmax, 8) 
if (modCi,8)20) 


* call toolbxCMOVETO,20,20* intCi/8)*height) 
i-i*1 
repeat 
endif 
endif 


* box part of the screen display 
x 


100 call toolbxCMOVETO, 20,20) 
rectC12220-height 
rect(22220-0 .5*widmax 
rect (3)220*descent*0 .5* leading 
rect(42220*C(widmax*20)-3 
call toolbxCPENMODE , 9) ! set penmode to pator 
call toolbxCFRAMERECT,rect) ! fill in rectangle 
call toolbxCMOVETO,20,20) ! upper left corner 


! start of hex values 
! set up rect bounds 

! leave room on left 

! leave room on bottom 
! leave room on right 


x 


* put out message at side of hex listing 
x 
cell toolbxCMOVETO, 20*widmax*4Q* 15,20) 
type "The boxed values have been" 
call toolbxCMOVETO, 20*widmax*40* 15, 20*height) 
type "stripped from the file " 
call toolbxCTEXTFACE, bold) 
call toolbxCMOVETO, 20*widmax*40*20, 20*2*height) 
type *,ofile 
call toolbxCTEXTFACE, normal) 
call toolbxCMOVETO,20*widmax*40* 15, 20+4*he ight ) 
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type “and stored in the file " 

call toolbxCTEXTFACE, bold) 

call toolbxCMOVETO, 20+widmax*49+20, 20+5*he ight ) 
type *,nfile 

call toolbxCMOVETO, 20*widmax*40* 15, 20+ 10*height) 
type "Press return to continue." 

pause 

stop 

end 


Listing 3 


$* »* 0 x 3 3» 3» HE »* »* »x* »* »* »* »* » * * * 


This file contains constants useful for accessing certain 
system globals kept off A5. You can get a pointer to this 
area from FORTRAN using the toolbx function. For example, 
to seed the Macintosh random number generator; 


include toolbx.par 
include a5glob. inc 
integer toolbx 


longCtoolbxCGETGLOBAL )*RANDSEED 225 


After executing the above, the rendom number seed will be 5. 
the globals accessable in this way ere given on page 34 of 
the QuickDrew Programmer's Guide in Inside Macintosh. 


This file has been graciously provided by Absoft and is not 
included on the MS Fortran Version 2.1 diskettes. Save this 
file under the name 'eb5glob.inc'. 


INTEGER ATTHEPORT 
PARAMETER CATTHEPORT=8) 
INTEGER THEPORT 
PARAMETER CTHEPORT=-4 ) 
INTEGER WHITE 
PARAMETER CWHITE=- 12) 
INTEGER BLACK 
PARAMETER (BLACK=-20) 
INTEGER GRAY 

PARAMETER (GRAY=-28) 
INTEGER LTGRAY 
PARAMETER (LTGRAY=-36) 
INTEGER DKGRAY 
PARAMETER CDKGRAY--44) 
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Fortran's World 


Fest Data 
RScrap.for import Tester 


Mark E. McBride 
MacTutor Contributing Editor 


The Clipboard and Desk Scrap Revealed 


Before moving to this month's topic, there are two items 
of news. First, I have received Apple's new 20 megabyte hard 
disk. As reported in the January issue of MacTutor the new 
HD20 will not work with the current 2.1 release of 
MacFortran, nor will it work on a Mac Plus or under HFS. 
Discussion with Absoft/Microsoft revealed that a solution 
will be forthcoming, probably with the 2.2 version (which is 
to be released sometime this spring or early summer). I will 
pass along any information I receive. 


[We at MacTutor think it is a disgrace that 
Microsoft is dragging their feet on the Fortran 
Upgrade. All the other languages for the Mac now 
run correctly under HFS. Fortran not only is buggy 
under HFS, it doesn't run at all! It is unfair to 
Fortran customers for Microsoft to be so slow to 
respond to the new systems, especially since they 
have taken great pains to see that their own 
internally developed software works! Obviously, 
those products which Microsoft distributes from 
other vendors take a back seat to their own products. 
Absoft has supplied Microsoft with the new version 
of Fortran and we think if Microsoft can't speed that 
product to market, they should return the rights back 
to Absoft so the product may be properly supported 
and upgraded in a timely manner. -Ed.] 


The move to the hard disk forced me to upgrade memory. 
Actually, I find it fairly amazing that I have written the 
current and all the previous columns using 128k and two 
drives. The only time I have felt constrained by the 128k is 
trying to debug programs with large data structures. The 
debugger takes about 40k, leaving very little room for your 
program. Note, however, that the shell application in the 
November 1985 issue was compiled and debugged on a 128k 
machine. 

The second piece of news of some importance is that the 
include files in MacFortran 2.1 have some errors in the 
parameter definitions. These errors became apparent the first 
time I tried to do memory management related toolbox calls 
from MacFortran. I talked with Absoft about the problems I 
was having and they disclosed the existence of the errors. 
Fortunately, these errors can be corrected by editing the 
toolbox include files. Listing 1 is a reprint Absoft sent to me 
which shows the correct parameter definitions for the affected 
toolbox calls. Be sure to correct the parameter definitions in 
both the toolbx.par file and in the memory.inc and 
OSutilities.inc files. You will need to correct these include 
files to use this month's function program. 
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A related note is that some of the update/ correction files 
have been appearing on Compuserve's MAUG board. They 
can be found under the Mac Developer's download library on 
programming tools. 


The Desk Scrap 


All of us are familiar with the clipboard in the standard 
Macintosh application. The clipboard holds a copy of the last 
item cut or copied so that it can be pasted back in at a later 
time. Further, we know that cutting or copying to the 
clipboard allows us to exit the application to the finder and 
then enter a different application with the clipboard intact (if 
the second application conforms to the standards for Cutting 
and pasting). The desk scrap is the vehicle for transferring 
information between applications. These other applications 
can be standalone programs or desk accessories. The desk 
Scrap normally resides in the heap in memory, but it can be 
moved to a disk by an application if memory space is a 
problem. Figure 1 illustrates the typical relationship between 
two applications, a desk accessory, and the TEscrap and the 
desk scrap. This article will focus on the use of a private 
scrap in an application with the desk scrap. 

The application program is responsible for insuring that 
the proper information is retrieved from the desk scrap or 
moved to the desk scrap. Although it is possible to read and 
write information directly to the desk scrap, most applications 
use a private scrap for cut, copy, and paste operations and then 
pass information to and from the desk scrap using routines 
supplied in the toolbox. Also, it is important to note that the 
rom text edit routines (accessed via TExxxx toolbox Calls) 
maintain their own private scrap. We will save the discussion 
of the TE scrap and the desk scrap for another time. The 
TEfromScrap and TEtoScrap Pascal calls are not part of the 
rom and are not availabe from MacFortran. 

Upon entry to an application the desk scrap resides on the 
application heap and has the format shown in Figure 2. The 
information in the desk scrap may be passed in more than one 
format. The two standard format types are 'TEXT' and 'PICT’. 
Desk scrap information of type 'TEXT" is simply a series of 
plain unformatted ASCII text codes. Desk scrap information 
of type ' PICT' is data representing commands to draw a 
Quickdraw picture (see Pascal Procedures, MacTutor Vol 1 
#11 October 1985 for an example of a Pascal routine which 
puts a ' PICT" type to the desk scrap). Inside Macintosh 

states that applications should write at least one of these two 
types of information to the scrap with the preferred format 
written first. Applications should be able to read at least one, 
if not both of these data formats. Additionally, user can put 
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Application #1 


Private Scrap 


"Y 


GETSCRAP 


Application #2 


Private Scrap 


GETSCRAP 
PUTSCRAP 


Desk Scrap 


ScrapStuff - Record 


scrapSize: 


Longint 


scrapHandle: Handle 
scrapCount: Integer 
scrapState: Integer 


scrapName: StringPtr; 


" 


DeskAccessory 


GETSCRAP 


Private Scrap 


hom 
TEFROMSCRAP 


Rom Text Edit Routines 


Private Scrap 


FIGURE 1 


data types of their own construction out to the desk scrap for 
passing of information to other applications which can 
recognize those private types. 


Using the Desk Scrap from Fortran 


From within an application there are several approaches 
to using the desk scrap. The basic approach I take is using 
general purpose subroutines to move data between an 
application's private scrap and the desk scrap. The basic 
toolbox calls available to use the scrap from Fortran are: 


Function InfoScrap :Inquire Deskscrap 


Function UnLoadScrap = :‘Deskscrap to disk 
Function LoadScrap ‘Disk to Deskscrap 
470 


Function GetScrap 
Function ZeroScrap 
Function PutScrap 


:Deskscrap to Private Scrap 
‘Empty Deskscrap 
‘Private Scrap to Deskscrap 


The source code for a routine called RScrap is given in 
Listing 2. The routine is accessed by ‘call RScrap(Priscrap, 
scraplength). The argument Priscrap is a handle to the 
application's private scrap. The length of the scrap copied to 
the private scrap is returned in the argument scraplength. If 
there was a problem in copying the desk scrap into the private 
scrap, the error code generated (a negative value) will be 
returned in the argument scraplength. RScrap is set up so that 
the first call to it from an application automatically forces a 
transfer of the desk scrap to the private scrap. Any further 
calls to RScrap during execution of the application transfers 
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the desk scrap only if the desk scrap's contents have changed 
since the last call. 

To be able to use the desk scrap effectively, RScrap 
defines the variables to be able to access information about 
the desk scrap using InNFOSCRAP. A data structure for the 
Scrap record is constructed using a pointer and offsets 
(reviewing sections 1.06 and 1.07 of the Toolbox appendix of 
the MacFortran manual might be useful at this point). This 
data record allows access to any of the information contained 
in the scrapStuff structure. This same technique is used to 
access information in a grafport record structure or a window 
record structure under MacFortran. RScrap gets the scrap 
record information as its first step. It uses this information, 
along with calls to GETSCRAP (with a NIL private scrap 
handle) and MAXMEM to see if enough available memory 
exists. 

Before calling the routine RScrap from the application, 
the user will want to create space on the heap for the private 
scrap. This handle is passed to RScrap as the Priscrap 
argument. RScrap makes a call to GETSCRAP with an 
appropriate specification of data type (e.g., 'PICT' or TEXT) 
and with the private scrap handle passed (RScrap could easily 
be modified to pass the type specification as an argument). 
GETSCRAP will resize the private Scrap to the appropriate 
size, move a copy of the data of the type specified from desk 
scrap to the private scrap, and return the length of the Scrap 
copied. If the length returned is negative, it represents the 
operating system error result or the scrap manager error result. 
Next, RScrap gets the current scrap count by making a call to 
INFOSCRAP and using the record structure offset given in 
scrapCount. If the user has a show clipboard option, then the 
loaded copy of the desk scrap could be displayed after exiting 
RScrap. 

A subroutine similiar to RScrap (called PScrap) could 
easily be developed which moves the private scrap to the desk 
scrap. The routine would need to pass the private scrap handle 
and length. The PScrap routine will need to zero the desk 
scrap with ZEROSCRAP and then use PUTSCRAP to copy 
the private scrap to the desk scrap. Development of PScrap 
will be left to the reader. 

Integrating the desk scrap and a private scrap in an 
application becomes a matter of calling RScrap and PScrap at 
the appropriate times. During the processing of the main 
event loop, there are five places where the user will want to 
concern themselves with the interaction of the private scrap 
and the desk scrap. First, the user should call RScrap during 
the initialization portion of the application program. This 
will load the desk scrap into the private scrap and will set the 
Count variable within RScrap to the current scrapCount value. 
Second , on each pass through the main event loop, after the 
check for SYSTEMTASK, the user will want to call RScrap. 
This allows RScrap to check for a change in the desk Scrap 
(because of a desk accessory) and recopy the desk scrap to the 
private scrap, when necessary. Third, in the routine that 
handles menu events, if the user selects a desk accessory the 
application should call PScrap, before calling the desk 
accessory. Fourth, the user should call RScrap or PScrap (as 
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Figure 2 


Resource Type 
4 bytes 


Length of Data 
4 bytes 


Ist 
Item Data uem 
(any length) 
Resource Type 
4 bytes 
Length of Data 
4 bytes 
2nd 
ItemData nem 
(any length) 
Resource Type 
4 bytes 
3rd 
item 


appropriate) during activate and deactivate events if a system 
window (i.e., desk accessory) is involved. Finally, the 
application should call PScrap to update the desk scrap when 
exiting the application. 


Importing Data via the Desk Scrap 
My original motivation for investigating the desk scrap 


was to see if I could import data for statistical subroutines 
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from either Multiplan or a word processor, simplifying data 
entry. The integer function Import given in Listing 3 (as part 
of the TestImport program) reads TEXT from the desk scrap 
into a Fortran array. The formal call to Import is: 


result«Import(A,rmax,cmax) 


where A is the array of maximum size rmax rows and 
cmax columns. The integer value returned will be zero if 
Import successfully read TEXT scrap into the array; otherwise 
the integer value returned will be the error code returned during 
the GETSCRAP process (which was returned by the call to 
RScrap) The function reads data from the desk scrap 
assuming that blanks, commas, or tabs separate the data 
values (thus handling data cut from Multiplan as well as a 
word processor). The routine will not handle non-numeric 
characters in the fields. If the desk scrap exceeds the 
dimensions of the array, the sub-array bounded by (rmax, 
cmax) will be read. If the data doesn't fill the array, the 
remaining elements of the array maintain their values from 
entry, but rmax and cmax are set to the size read in. Elements 
in the scrap which are not specified (i.e., two succesive tabs or 
commas) are left unchanged in the array. 

Examination of Listing 3 reveals how the function 
works. First, space for the private scrap is allocated on the 
heap using NEWHANDLE. Then the 'TEXT' contents (if 
any) of the desk scrap is copied to the private scrap using the 
routine RScrap. The private scrap is then locked in memory 
for the duration of the function. If the RScrap routine returned 
a negative result, then the function sets its result to the error 
code, unlocks and disposes the private scrap, and exits. 


If the RScrap routine returns a positive number for 
scrapLength, then data of type "TEXT was copied to the 


private scrap and its length is the positive number returned. 
The Import function result is set to zero. In this case, the 
function loops through the private scrap creating a string 
variable for each data value found and counting the number of 
data elements for that line. If data is found for a particular row 
and column element then the data element is read into the array 
A. If no data is found (e.g. two commas or tabs in a row), 
then the element of A is left unchanged. The process 
continues for as long as their is data in the private scrap or 
room in the array A. 

After all the data has been read into the array A, the 
values of rm and cm are reset to the largest values used (if less 
than the original values passed). Finally, the private scrap is 
unlocked, its handle disposed, and the function exits to the 
calling program. 

A short program to test the function is also given as part 
of Listing 3. This program simply prints the data array A to 
the screen twice, once for the full dimensions of A and once 
based on the dimensions returned by Import. A test data set is 
given in Listing 4, but your own could be created with any 
text editor or Multiplan. The test data contains many strange 
combinations of commas, tabs, and spaces to separate the 
values. Figure 3 shows the screen from the program in 
Listing 3 and the data from Listing 4. 
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This ends our introduction to the desk scrap. Till next 
time, happy computing. 


Listing 1 


* This file contains parameter definitions which were 
incorrect 

* in the initial release of Microsoft Fortran 2.1. Several 0S 
* traps were defined with the ‘save AG' flag set to zero (this 
* indicates that AØ should be restored) for OS functions which 
* return a value in AQ. 

* These traps are found in the following Fortran include 
files: 


x toolbx.par 

* memory. inc 

x OSutilities. inc 
x 


* Maxmem is a special case in that it returns 2 values. 
Pascal 

* returns one of these in the function's argument; the 

* FORTRAN toolbx.sub function has no provision for this. For 
* those requiring the Grow value, the MAXMEM2 definition 

* below should work. MAXMEM will return only 

* the size of the largest contiguous block, MAXMEM2 will 

* return only the Grow size. 


* Function MaxMem CVAR Grow: Size): Size; 
INTEGER MAXMEM 
PARAMETER CMAXMEM-Z' 1 1DA0Ø24' ) 
INTEGER MAXMEM2 
PARAME TERCMAXMEM2=Z ' 11DA00A4 ' ) 


* Function NewHandle CLogicalSize: Size): Handle; 
INTEGER NEWHANDLE 
PARAME TERCNEWHANDLE=Z ' 12200048 ' ) 


* Function HandleZone (H: Handle): THz; 
INTEGER HANDLEZONE 
PARAMETER CHANDLEZONE2Z ' 12680048 ' ) 


* Function RecoverHandle (P: Ptr): Handle; 
INTEGER RECOVERHANDLE 
PARAME TERCRECOVERHANDLE=Z'‘ 12880044 ' ) 


* Function NewPtr (LogicalSize: Size): Ptr; 
INTEGER NEWPTR 
PARAMETER CNEWPTR-Z' 11E200A8 ' ) 


* Function GetTrepAddress CtrepNum: INTEGER): LengInt; 
INTEGER GETTRAPADDRESS 
PARAMETER CGETTRAPADDRESS=Z' 146000A2 ' ) 


* Function GetZone : THz; 
INTEGER GETZONE 
PARAMETERCGETZONE2Z ' 11A0004A8 ' ) 


* Function PtrZone (P: Ptr): THz; 
INTEGER PTRZONE 
PARAMETERCPTRZONE2Z ' 14880048 ' ) 


subroutine RScrap(Priscrap, screplength) 


x 

x This subroutine reads the deskscrap into a private scrap 
* located at the handle given by Priscrap. It only loads the 
* deskscrap if the scrap has changed (read is automatically 
* forced during the first call) and if there is enough 
available 

x memory to read in the deskscrap. 

* Mark E. McBride 

* 211 N. University Ave. 

* Oxford, OH 45056 

* (513) 523-1438 

x 
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implicit none ! keep us out of trouble 
include scrap. inc 
include memory. inc 

x 


* Variables needed to get private scrap 
x 


! handle to private scrap 
! length of private scrap 
! desk scrap offset 

! scrap count 


integer*4 Priscrap 

integer*4 scraplength 

integer*4 offset 

integer*2 Count 
* This defines the PscrapStuff information record structure 
x 

integer*4 PscrepStuff ! Pointer to Infoscrap record 
integer*4 screpSize ! size of desk scrap 
integer*4 scrapHandle ! handle to desk screp 
integer*2 scrapCount ! count changed by Zeroscrap 
integer*2 scrapState ! tells where desk scrap is 
integer*4 scrapName ! pointer to desk scrap name 


parameter(scrapSize =z'Ø') ! offset to scrapSize 
parame ter (scrapHandle=z'4') ! offset to scrapHandle 
parameter(scrapCount =z'8') ! offset to scrapCount 
parameter(scrapState sz'A') ! offset to scrapState 
parameter(scrapName =z'C') ! offset to scrapName 


x 
* Other general variables needed 
x 


integer*4 toolbx, Grow 
* Keep Count between successive calls of RScrap 
x 

Save Count 


* Initial data values to force reading of desk scrap for 
first 
* call of RScrap 


data Count, Grow/-9999, 100/ 


* Begin subroutine by checking to see if desk scrap has 

* changed then copy only if 'TEXT' available in desk Scrap 
and 

* if there is memory available. 

x 


PscrepStuffztoolbxCINFOSCRAP) ! get desk Scrap info record 
if Cword(PscrapStuff+scrapCount).ne.Count) then 
Count=word(PscrapStuf f *screpCount )! scrap changed 
Grow=toolbx(MAXMEM,Grow) ! compact & check memory 
! check for ‘TEXT’ without copy 
scrap length=toolbx(GETSCRAP,@, 'TEXT', offset?) 
if CCscraplength)=0).and.(scraplength<Grow)) then 
! get available scrap 
scrap length=toolbx(GETSCRAP,Priscrap, ' TEXT ' , offset) 
Count=word(PscrapStuff+scrapCount) ! update Count 
end if 
end if 
end 


Progrem TestImport 


implicit none ! keep us out of trouble 
include quickdraw. inc 

include misc.inc 

include event. inc 


integer*4 kmax,nmax, toolbx, i,j, Import 
real*8 BC10,5) 

data B/50*-1.0/ 

date nmax,kmax/19,5/ 


write(*,*) ‘The matrix is set to 18 rows and 5 columns max 
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if CImport(B, nmax,kmax)=8) then 
write(*, *) 
write(*,*) ‘The matrix as the full 10 by 5 ' 
writeC*, 100) ((BCi, 32, j=1,5), i=1, 10) 


100 format(5f8. 1) 


write(*,*) 

call toolbx(MOVETO, 388, 108) 

type ‘Press return to continue' 

pause 

call toolbx(MOVETO, 300, 160) 

writeCX*,*) 

writeC*,*) ‘The submatrix of the 10 by 5 which was 


read in' 


do 128 i-1,nmax 


120 writeC*, 100) (BCi, j), js 1, kmax2 


x 
x 
x 
x 


write(*,*) 
call toolbxCMOVETO, 300, 258) 
type ‘Press return to continue' 
pause 
else 
write(*,*) 
writeC*,*) ‘No type TEXT found in Clipboard' 
end if 
stop 
end 


integer*4 function Import(A,rm,ca) 
This function pulls en array of numbers from the deskscrap 


The array size is passed in cm (number of columns) and rm 
(number of rows). The program reads in the data assuming 


that 


x 


blanks, commas, or tabs separate the data values. The 


routine 


x 


$* »* »* »* »* HH * * * 


will not handle non-numeric characters in the fields. 

If the deskscrap data exceeds the dimensions of the matrix 
only those elements within (rm,cm) will be read. If the 
data doen't fill the matrix, the remaining elements of the 
matrix maintain their values from entry and rm,cm are set 
to the size read in. 


Mark E. McBride 


implicit none ! keeps us out of trouble 
include window. inc 

include dialog. inc 

include quickdraw. inc 

include misc. inc 

include scrap. inc 

include memory. inc 


integer*4 rm,cm ! maximum number of rows and 


columns 


real*8 ACrm,cm) 
character*256 strg 


! erray of elements to be passed 
! general purpose string 


variable 


integer*4 i,j,col,row,cmax,rmax ! assorted looping 


variebles 


integer*4 toolbx,temp ! toolbox interface 

integer*4 PriScrap ! handle to copy of desk scrap 
integer*4 length ! private screp length 
integer*4 space,comma, tab,return ! deliniting 


characters 


integer*1 c1 
character*! ch 
equivalence Cc1,ch) 
parameter (space=32) 
parameter Ccomma=44) 
parameter (tabz9) 
parameter (return=13) 


! single character as integer 
! single character as character 
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* Set up scrap handles 
x 


Import-- 182 

length=8 

Pr iScrap=too1bx(NEWHANDLE , 2 ) 

! get handle for private scrap 

call RScrep(Pr iScrep, length) 

! read in scrap of type 'TEXT' 

call toolbxCHLOCK,PriScrap)! lock copy down 

temporarily 

if Clength > Ø) then 
Impor t=9 
temp=long(PriScrap) ! get ptr from handle to data 


* get the data 
x 


! got something in scrap 


i-0 

cols 

row= | 

cmax=0 ! observed maximum column 
rmax=0 ! observed maximum row 


while Ci<length) 
whileCbyteCtemp*iJ-space .and. i<=length) 
! skip leading spaces 
i=i+1 


repeat 

if Ci» length) goto 10 

j^! ! indexes current character in strg 
strg="" ! set current string null 
c l=byte(Ctempti ) ! get first byte 

while 


((cl.ne.space).and.(ci.ne.comma).and.(cil.ne.tab).and. 
1 (cl.ne.return)) ! process if not separator 
strg(j:j=ch 
j*j*1 
i=itl 
if Ci<=length) then 
c l=byteCtempti) 
else 
cl=return 
end if 
repeat 
col=col+1 
! bump column counter , 
if (Ccolc=cm).and.Cstrg.ne."")) read(strg, *) 
ACrow,col) ! read data value 
cmax=min(col, cm) 
if Ccl=return) then 
! check for end of line 
rmax=row 
row=rowt | 
if Crowrm) goto 18 
col=8 
end if 
izi*1 
repeat 


! stuff character to string 


! test for end of scrap 


! reset column used count 


! check array boundary 
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end if 
1g call toolbxCHUNLOCK ,PriScrap) 
! unlock copy of scrap 
call toolbxCDISPOSHANDLE,PriScrap) ! dispose 
rm-rmax 
! set rm for exit 
cm=cmax 
! set cm for exit 
return 
end 


Listing 4 
A random sample of test date to try 


111,,1111 
22,222 2222 22222 
3,33,333 3333 33333 333333 
4,44,444 4444 44444 
,55,555,5555,55555,555555 
6 66 666 6666 66666 

7 TtT T TUI 
B 88 888 8888 88888 888888 
9 99 999 9999 99999 


The matrix is set to 10 rows and 5 columns maximum 


The matrix as the full 10 by 5 

1.0 11.0 =f; 1111. 
22.0 222. 2222. 
33.0 333. 3333.0 33333. 
44.0 444.0 4444.0 44444. 


0 0 -1 

0 0 

0 0 

0 0 
99.0 555.0 5555.0 55555. 

0 0 

0 0 

0 0 

0 0 

0 .0 


22222. 


1 
3 
4. 
1 
6. 
p» 


66.0 666. 6666.0 66666 
77.0 072. 7777.0 77777. 
88.0 888. 8888.0 88888. 
99.0 999. 9999.0 99999. 
-1.0 d. =] =] 


oOoooooooo 
OOOOOOOoOoO0 


- O © 


Press return to continue 


Fig. 3 Program reads and displays clipboard 
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Fortran's World 


HFS Issues and Answers 


This month's columns covers a variety of topics and 
issues, some of which I have come across and some which 
readers of MacTutor have sent in. Readers can contribute 
easily by sending suggestions for future column topics, bug 
finds, or general questions about programming the Mac in 
Fortran. Send all inquiries to me care of MacTutor. Now, on 
to the topics. 

Version 2.1 and the Mac+ 

A more correct title for this section is Version 2.1 and 
HFS. As reported in MacTutor (Vol. 2 No. 5 May 86), 
Microsoft Version 2.1 does not work with HES. [See 
Microsoft's reply in the box at the end of this article. -Ed] 
The compiler eventually gets lost in locating its files, even 
when all files are on the desktop and no folders reside on the 
disk. But do not completely despair, because you can run 
V2.1 on the Mac+ and on a rom upgraded 512k Mac if you 
use MES under Finder 4.1. 

To convince myself of this, I conducted a test of V2.1 on 
several machine configurations. I used four different machine 
configurations. Table 1 summarizes the results. In the 
following configurations, MFS System refers to MFS 
formatted diskettes with the old system (pre-Version 3.0) and 
Finder 4.1, while HFS system refers to HFS formatted 
diskettes with the new system (Version 3.1.1) and Finder 5.2. 
All tests were conducted with MS Fortran Version 2.1. 

Configuration A was a 512k Mac with the rom upgrade 
and a two disk (400k each) MFS system. Configuration B 
was a 512k Mac with the rom upgrade and a one disk (800k) 
MFS system. Configuration C was a Mac+ with a one disk 
(800k) MFS system. Finally, configuration D was a 512K 
Mac with the rom upgrade and a one disk (800k) HFS system. 

In case the reader was wondering how an 800k MFS 
System was created, here are the steps necessary (This tip was 
passed to me by Absoft tech support. Absoft tech support 
hadn't tried this, but it was suggested to them by another 
user): 

800k MFS Diskette 

1. Initialize an 800k diskette with the new system (3.1.1) 
under Finder 5.2. 

2. Boot a system disk with the old system and Finder 4.1. 

3. Eject the old system disk and insert the initialized 800k 
diskette in the 800k internal drive. 

4. Choose 'Erase' from the 'Special' menu of Finder 4.1. 

5. Move the old system, Finder 4.1, MS Fortran, and all other 
files onto the 800k MFS diskette, then reboot. You now 
have an 800k MFS system for use on a 512k Mac with the 
rom upgrade or on a Mac+. 

In addition to trying four different machine 
configurations, I also tried three different types of programs. 
The first program was the Shell program presented in 
MacTutor (Vol. 1 No. 12, November 1985). This program 
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uses several toolbox routines and has an event loop structure. 
The second program was an old Probit regression program I 
transferred down from the mainframe. The code structure is 
sequential from start to stop. The reason for picking this 
program was that the program opens a data file on a disk using 
a hard-coded 'diskname:filename' in the source, i.e., 
open(25,status-"KEEP" |f ile2"Probit.Data") 

[Note: The standard JCL used on mainframes to link a 
Fortran file number with a physical device does not exist on 
the Mac. Instead, that association is done directly in the 
Fortran code with an open statement. -Ed] 

The third program was the Probit regression program 
modified to use the 'stdfil' subroutine (see MacTutor Vol. 2 
No. 2, Feb. 86) to get the data file name to open on the disk, 
L6. 

ok=stdfilC1,'', fname, 1,  TEXT' ) 

if Cok) then 

open(25, status="KEEP", f ile=fname) 
else 


goto 13 
endif 


The reason for doing this was to check for the ability to 
run the resulting compiled and linked application under MFS 
or HFS using the standard getfile and putfile routines as used 
by 'stdfil', with the new ROMS! 

AS shown in Table 1, each combination of program and 
machine configuration is tested for compiling/linking, running 
under MFS, and running under HFS. The Tunning under 
HFS' category meant that the fully compiled and linked 
program was moved over to an 800k HFS system and run 
under System 3.1.1 and Finder 5.2 

As can be seen from Table 1, Version 2.1 will run under 
MES, even on a Mac+ or rom upgraded 512k Mac as long as 
you stay with MFS. The major exception to this statement is 
that unmodified use of the MS Fortran supplied subroutine 
‘stdfil’ will not work under MFS with the new roms. If the 
program requires a datafile name during execution, you can 
either prompt the user for the name using an input routine of 
your own design or attempt to modify 'stdfil' so it works with 
the new roms. Hopefully, all of this will be history by the 
end of summer with the release of Version 2.2, which has 
HFS compability. [Other apparent problems are you can't have 
more than three files opened at once or more than two files if 
you use the default printer file. This can be corrected by 
setting the linker z option for more heap space, or declaring a 
large array in a dummy subroutine. Also, the full listing 
option inserts a funny page control character that causes the 
imagewriter to go beserk ejecting pages, and hangs the Mac, 
when printing from Edit. So you can't print the full listing 
file, except from the compiler print option. -Ed.] 

Debugging Event Loops 

The source code debugger is one of the most useful 
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features of MS Fortran. On many occasions, this debugger 
has saved me considerable time in locating a program bug. 
Eventually, as you develop Fortran programs using the Mac 
user interface, you will need to debug an event loop. If you 
try single stepping through the program, however, you will 
find that you cannot debug the event loop. This happens 


program Hi Ibert 
eventaask s -1 pop bes 
window=toolbx(FRONTHINOG ES v. E Rute m 
cali toolbxCCLOSEHINDOU fTAN 

call toolbx(TEINIT> — | EEMe: Soft breakpoint Mun 

call prport(PROPEND) — D ENSEM 

call prport(PRINTOEFAUL Vi! lam 
coll prportCPRCLOSE > Hu 
menuhand estooibxCGETMEIT | i 
call toolbx( INSEFRMENU, mii ER 
call toolbxC(ADORESMENU, pu AN 
menuhand es too I bx (GETME! 1 ? 
call toolbxCINSERTMENU, 2 5À 
menuhand l e= too | bx(GETMEN:::::: PZS 

call toolbx¢ INSERTMENU, | ~ Figure 1 


call toolbxCORRUnENUBAA [O il 
g-storage=toolbx(PTR, gO 


Defauk Application Window 


because the debugger has its own event loop and is processing 
all events. There is a simple and easy way around this 
‘apparent’ problem. 

The debugger has two types of breakpoints: soft and 
hard. A soft break point is set by moving the cursor (the left 
pointing arrow) to the source statement where you want to set 
the soft breakpoint. Once you set the soft breakpoint, then 
you can hit 'return' which executes all statements from the 
current statement (indicated by the rectangle box) up to and 
including the soft break point statement; or you can type 
'command-g' which executes all statements from the current 
statement up to and not including the soft break point. A hard 
break point is set by clicking the number of the statement to 
be stopped at. Generally, in the process of locating the 
statement for which a hard breakpoint is to be set the soft 
breakpoint cursor also moves. Issuing the home cursor 
command (command-h) returns the soft breakpoint to the 
current statement. After setting the hard breakpoint(s), the 
proceed to breakpoint command (command-x) executes the 
program up to but not including the hard breakpoint 
statement. If you wish to stop at that same breakpoint again, 
always single step through the statement for which the 
breakpoint is set. This is necessary because the debugger 
clears any breakpoint set on the current statement when 
command-x is pressed. 

Whenever you set a soft or hard breakpoint the debugger 
executes a send-behind on all its windows and effectively 
‘hides’ itself until the breakpoint is encountered. Thus, by 
setting a hard break point at the call to the routine you are 
interested inside the event loop, you can get full processing of 
your event loop until you get to the breakpoint. When the 
breakpoint is encountered, the debugger issues a bring to front 
for the source code window and you are back in the full 
debugger. 

By using soft and hard breakpoints, you can achieve 
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several goals from within the debugger. Figure 1 illustrates 
the setting of a soft breakpoint near the start of the program to 
remove the default window MS Fortran creates. By setting the 
soft breakpoint after the call to FRONTWINDOW and 
CLOSEWINDOW and then pressing ‘return’ the default 
window is removed without bombing the debugger. Figure 2 
shows the result of this process. 

Figure 3 illustrates setting a hard break point within the 
menus subroutine of a typical event loop. Notice that the hard 
breakpoint is set after the call to MENUSELECT. If the hard 
breakpoint had been set for MENUSELECT statement, then 
you would be unable to track the mouse within the menus. 
Figure 4 shows the program running, with the debugger in the 
background, after issuing the execute to breakpoint command. 


" 


zz hilbert.for SSS 


programa Hilbert 


00656 eventaask = -1 

00660 window=too | bx (FRONTH | NDC eet 

0066 1 call toolbxCCLOSEHINDOU Sees 

00666 call toolbx(TEINIT) 2i 
006/02 prrechd|=too | bx (NEHHF «- Curentstatementand — EE 
00671 call prportCPROPEN) soft breakpoint p 
00672 call prportCPRINTDEFRUL 

00673 cal! prport(PRCLOSE > — — 


aenuhandlestoo!b»x(Gl 
cal! toolbxCINSEFÀHENU 


call toolbxCINSERTHENU, 
menuhand | e=tool bx (GETME! 
call toolbxCINSERTMENU, 
menuhand | e= too! bx (GETME 


BÉ No defaut window present | 


Figure 2 


BH 


cal! toolbxCINSERTHMENU, tR 
call toolbxCDRALPENUBRR TY 
g-storage=toolbx(PTR, g. T 


J 


D ME = softbreakpoint, return to curent 
DH statement with command-h 


014 


2 statement number 


Figure 3 


cose (File) 
aenuhand! estoo bx CGB Eh 


Finally, Figure 5 illustrates the return of the debugger when 
the hard break point is encountered with the variable window 
showing which menu item had been selected. The variable 
window indicates that the second menu item of the Options 
menu (ID=32) had been selected, leading to the breakpoint. 

Is handling of menu related events during debugging 
altered by the presence of the debugger menu? Surprisingly, 
and convienently, no. When the debugger is in the 
background and your menus have ID's different than 5, then 
there will be no problem. Judicious use of hard and soft 
breakpoints, particularly within event loops, can speed 
program development considerably. 

Reader's Questions and Tips 
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Debug € Fil Edit Options 


z Graph Window E 


application is running and handling events. The 
debugger is in the background and will not reappear 
until a breakpoint is encountered. 


All of the application's menus are fully functional, as 
are all other events. 


Ld 


_ Debug é File Edit Options 
aC] 


hilbert.for E] MENUS Memory 280 


i tem4=menuse lecti on(2) [| eenusel ection Integer*2 32 O 
select case (menuselect ET 2 2 

case (Options) HH 

menuhand l e= too | bx (GHEE 

select case (menuse i 
Hard breakpoint Is encountered after menu tem was 
Selected causing the program to stop. Debugger 
window comes to the front and control of events 
returns to the debugger. Typing command-v causes 
the variable window to appear. The variable menu- 
Selection(1)(2) indicate that menu ID=32, tem 2 was 
selected. 


Loi 


enunand | e=toolbx (Ga 
select case(menuseld "2 | 
case(PSetUp) aj a 


Q: A letter from Edward Groth of Scottsdale, AZ arrived 
the other day. The two listings he included are reprinted as 
Listing 1 and 2. As can be seen, both concern problems with 
large arrays (approx. 90,000 elements). As Mr. Groth 
correctly states in the listings, the programs don't work on the 
512k Mac with version 2.1, but do work under Absoft version 
2.0b (the predecessor to version 2.1). 

A: After conversations with Absoft technical support 
(who have always been helpful), the reason for the two 
programs not working was found: a serious bug in the 
compiled code which could potentially affect any array which 
takes up more than 32k of space. The bug does not always 
show up. For example, if Listing 1 is run under Version 2.1 
on the Mac+, it works fine; as will Listing 2 if all integer 
declarations are integer*4 instead of integer*2. Again, 
however, Absoft tech support stated that the bug could occur 
for any array (real or integer) which occupies more than 32k of 
space. So if you are using large arrays, watch out. 

I inquired about a work around or patch. There is no 
work around for this bug. Absoft said a patch would not be 
forthcoming unless the release of Version 2.2 is significantly 
delayed since 2.2 does not contain this bug (my beta-test copy 
of Version 2.2 ran both programs properly! ). As to why 
version 2.0b correctly handles Listings 1 and 2, but 2.1 does 
not, the core compiler routines which deal with arrays were 
completely rewritten between the two versions to improve 
performance [In other words, it's a new product! -Ed.] 
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Q: Mr. Groth asked a second question relating to the 
sequence of compile, link, Rmaker. The bottom of page 2 of 
the Rmaker manual supplied with MS Fortran states that 
Rmaker only works with resource sizes of 32k or less. Well, 
if you have to link the runtime before you add the resources 
with Rmaker (since the MS Fortran linker only understands 
output from the compiler), then it appears that only 
applications of size 32k or smaller can be created as a 
standalone application with resources added. 

A: The limitation on Rmaker is due to a bug in the 64k 
roms (not the new 128k roms). Apple Tech Note #63 
contains the full details (the Apple Tech Notes can be found 
on Compuserve's Mac Developer Maug, DL8). Evidently, bit 
15 in the size of the resource is handled improperly causing 
any resource whose size has bit 15 set would be written by 
WriteResource as having size 0. Thus resources of size 0-32k 
can be written, 32k-64k can't, 64k-96k can, etc. If your 
application uses the toolbox routines WriteResource or 
GetHandleSize, you may want to look at Apple Tech Note 
#64 which gives a work around for the problem. 

Tech Note #64 solves the problem for an application that 
uses WriteResource with the 64k roms, but does not solve the 
problem for using Rmaker and a compiled, linked Fortran 
application. However, a solution is Straight forward. Instead 
of including the compiled, linked code using the include 
Statement, append the new resources to the compiled, linked 
application. For example: 

instead of : 


1 


Hilbert 
APPLFORT 


include: hilbert ap] 
. (your resources) 
use: 


Ihilbert ap] 
APPLFORT 


.... (your resources) 

This second approach also can be used to add resources to 
an unlinked application you are still debugging. By setting 
the 'APPLFORT' tags, the debugger will still recognize the 
compiled code. 

Tip: Mr. Bob Andris of Saratoga CA writes in with a 
tip for attaching assembly language to your Fortran programs. 
If the assembly subroutine is compiled under the MDS, there 
is a simple and elegant way of getting the subroutine into the 
form that the Fortran linker wants. In the MDS Linker file, 
make the Output file name 'abcdef.sub' and then add a line you 
wouldn't normally have in an application's Linker File, 
namely '/Data. The Linking and Mapping then produce a 
psuedo' application that is just the compressed DATA 
application you need. Just link it in with the Fortran linker. 
For example: 


f YourProg 
f abcdef .sub 
1 fTl.r1 
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o YourProg 


Thanks, Bob. 

Q: Mr. Jim Bishara of Metairie, LA inquires as to 
whether there is an equivalent statement to the basic command 
FRE(-1). 

A: The basic FRE(-1) command returns the number of 
bytes of available space on the Macintosh heap with MS 
Basic. The following code compacts the current heap zone, 
purges all purgeable blocks from the zone, then returns the 
number of available bytes in the largest contiguous free block 
in the zone. Be forewarned though, that all the space is 
unlikely to be available since some resources may be read back 


into memory the next time they are needed. 
include memory. inc 
integer*4 Grow 


Grow= 100 


Grow-toolbxCMAXMEM, Grow) 

After execution of the toolbox routine, Grow will contain 
the number of available bytes in the large contiguous free 
block. This probably is preferable to using FREEMEM, 
since FREEMEM counts all available bytes, whether 
contiguous or not. If the are any non-relocateable blocks in 
the heap, then not all the memory returned by FREEMEM 
will be available. 

Other letters have inlcuded more tips, questions, and 
suggestions for future topics. Please keep the letters coming 
and I'll try to cover as many of the topics/issues as I can in 
future columns. Next month's column will cover using the 
print manager, pictures, and the deskscrap all in one graphing 
application! Till then, happy computing. 

Listing 1 

program MEMTEST 

implicit none 

integer z,zsize,i,j 

virtual z(0:300,0:300) 

type "Array Size? ";accept zsize 

do (j20,zsize) 

do (i=8,zsize) 
zi, j2si*(zsize* D*j 


repeat 
repeat 
write(9,*) ‘Upper Left Corner ^"',z(0,0) 
write(9,*) ‘Upper Right Corner ',z(zsize,0) 


write(9,*) ‘Lower Left Corner ^"',2(0,zsize) 

writeC9,*) ‘Lower Right Corner ',z(zsize,zsize) 

write(9,*) ‘Finished’ 

pause 

end 
* This works right in Absoft V2.0b but gives incorrect values 
* in MS V2.1 for the upper left and lower left corners when 
* zsize is 219 or greater. 
Listing 2 

program MEMTEST 

implicit none 

integer*2 z,zsize,i,j 

dimension z(0:400,0:400) 

type "Array Size? ";accept zsize 

do (i20,zsize) 

do (j=0,zsize) 
z(i,j)=itj 
repeat 

repeat 

write(9,*) ‘Finished’ 
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pause 

end 
* Listing 2 works OK with zsize of 218 or less. With zsize 
x (array size) of 219 or larger up to and including 309, the 
* system crashes with the dreaded black bomb or worse yet, it 
* completely hangs after trying to destroy the machine. Try 
* about 280.This works fine in Absoft V2.0b for all values of 
* zsize(2300. Obviously it should work on a 512k Mac but 
* does not do so under the official 2.1 MS Fortran. 

Teble 1 
hin nfiguration 
A B C D 

Shell Program 

compile/link yes yes yes no 

run under MFS yes yes yes n/a 

run under HFS yes yes yes n/a 

1 

compile/link yes yes yes no 

run under MFS yes yes yes n/a 

run under HFS no no no n/a 
Probit Version (stdfil) 

compile/] ink yes yes yes no 

run under MFS no no no n/a 

run under HFS no no no n/a 


Configuration A: A 512k Mac, with rom upgrade, using two 
400k disks with the MFS system. 

A 512k Mac, with rom upgrade, using one 
808k disk with the MFS system. 

A Mact using one 880k disk with the MFS 
system. 

A 512k Mac, with rom upgrade, using one 880k 
disk with the HFS system. 


Configuration B: 
Configuration C: 


Configuration D: 


Microsoft Responds 


This is in response to the May issue's complaint about 
Microsoft Fortran for the Macintosh. Microsoft is committed 
to making Fortran, as is the case with all our products, the 
best it can be. We appreciate MacTutor's criticisms, and are 
taking to heart all suggestions for improving the product. 

Microsoft has received the first installment of the next 
version of Fortran from Absoft. Since then, we have been 
putting it through extensive internal and outside testing, and 
Absoft has characteristically been doing an excellent job of 
fixing bugs and implementing changes recommended by the 
testers. What will result from our thorough quality control 
process is another version of Macintosh Fortran that will best 
meet the user's needs. 

We wish we could announce a release date, but that would 
be a disservice. Our philosophy is to work hard and release 
great products. One cannot accurately predict what changes 
will be necessary until after the testing is complete, and we 
will not release a product that is anything but the best quality. 
This next release and its timeliness, however, are a top 
priority. When available, it will have additional useful features 
as well as making full use of your new machines. 

We want to straighten out one inaccuracy in the May 
Fortran column; Version 2.1 does work on the Mac Plus. You 
must use the old versions of System and Finder 4.1 on the 
Fortran disk. You cannot be using HFS folders. - Ray Bily, 
Product Manager, Apple Languages, Microsoft Corp. 
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First Class Citizens in MacScheme Scheme 


This month the Lisp Listener will feature an in depth 
description of MacScheme. This description comes from 
William Clinger of Semantic Microsystems, the developers of 
MacScheme. 

Imagine a programming language in which every number 
must be given before it can be used in an expression. For 
example, you could not print the circumference of a unit circle 
by saying "write (2 * 3.14159)"; you would instead have to 


say something like 

let two z22 

let pi - 3.14159 
two. pi - two * pi 


foo Ctwo_pi) 

Of course, such a language would be very clumsy. 
Nobody would want to use it. A student of programming 
languages would say that the problem with the language is 
that it treats numbers as second class citizens. 

First class citizens have the right to remain anonymous. 
They have an identity that is independent of any names by 
which they may be known. Further more they have the right 
to participate in any activity sponsored by the language. If the 
language has arrays, then any first class citizen can be an 
element; if the language has assignments, any first class 
citizen can be stored in a variable. If the language can pass 
arguments to procedures, any first class citizen can be passed; 
if procedures can return results, any first class citizen can be 
returned. 

Numbers are so important that they are first class citizens 
of nearly all programming languages. In some languages 
numbers are the only first class citizens. In many languages 
the only first class citizens are those that are easy to fit into a 
machine register. 

Arrays are important and have been around a long time, 
but how many programming languages really treat arrays as 
first class citizens? Also, how many languages allow you to 
create a new array without giving it a name? Do they allow 
you to return an array (not just a pointer to the array) as the 
result of a procedure call? Do they allow arrays to appear on 
the right hand side of an assignment statement? First class 
arrays as in APL have a radical impact on programming style. 

Procedures have been around a long time also, and most 
programming languages allow procedures to be passed as 
arguments to other procedures. Do they allow you to create a 
new procedure without giving it a name? Can you retum a 
procedure as the result of a procedure call? Can a procedure 
appear on the right hand side of an assignment? 

The most accessible of the languages with first class 
procedures are the two modern dialects of Lisp known as 
Scheme and Common Lisp. The following contains samples 
of First Class procedures using MacScheme. 

An anonymous procedure is written as a lambda 
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expression beginning with the keyword lambda, followed by a 
list of arguments, followed by the procedure body. The lambda 
expression evaluates to a procedure. 

>>> Clambda (x) (+ X 125) 

# PROCEDURE»? 

What can you do with an anonymous procedure? 
Anything you can do with a named procedure. For example, 
the second argument to the sort procedure that defines an 
ordering on the objects to be sorted. If you already have a 
procedure that defines the ordering you want, you can refer to 
it by one of its names: 

»»(sot '(135 79 8 6 4 2 B) >?) 

(9876543210) 

»»>Csort '(1357986420)0») 

(98765432109) 

If you don't already have the procedure you want, you can 
create one with a lambda expression. There's no reason why 
you should have to think up a name for it: 

>>> (sort 'C"Even" “mathematicians” "ere" "accustomed" 
"to" "treating" "functions" "as" underprivileged” "objects") 

(lambda (x y) 
Cor (<? Cstring-length x) Cstring-length y)) 

("as" "to" "ere" "Even" "objects" "treating" 
"functions" "accustomed" “mathematicians”  "underprivileged") 

Names come in handy when you want to write a recursive 
procedure, however. The rec expression is convenient for that 
purpose. In the example below, the (rec fact ...) syntax 
introduces a new variable named fact whose value is the value 
of the lambda expression. 

>>> (rec fact 

(lambda (n) 
Cif (zero? n) 
1 


(* n (fact. (- n 1)))))) 


8«PROCEDURE fact? 

The variable named fact is visible only within the lambda 
expression, however. If we were now to ask for the value of 
fact, Scheme would say that fact is an undefined variable. 
Thus the result of the rec expression is just as anonymous as 
the result of a lambda expression. Admittedly its printed 
representation includes a name, but that name is nothing more 
than a comment generated by the Scheme system as it 
attempts to be helpful. 

We can use the recursively defined anonymous procedure 
as the first argument to the map procedure, which will call the 
procedure on every element of its second argument and return a 
list of the results: 


>>) (map (rec fact (lambda (n) Cif (zero? n) 
(fact (- n 1)))))) 


] (*n 


(0123456789 10 11 125) 
(112 6 24 120 720 5040 40320 3629880 3628800 39916800 
41900 1600 ) 
In MacScheme, the map procedure is also called by its 
traditional name mapcar. The define expression below creates 
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a new global variable named call-on-every whose initial value 
is the contents of the old variable map -- that is, the map 
procedure. 


>>> (define call-on-every map) 

call-on-every 

If we want to create a procedure and a variable to hold it, 
we create the procedure using lambda expression and we create 
the variable using a define expression: 


>>> (define cube (lambda) (x) Cexpt x 3))) 
cube 

>>) cube 

8 PROCEDURE cube»? 

>>> (map cube '(0123456789 105) 


(Ø 1 9 27 64 125 216 343 512 729 1000) 

If you don't like writing (define cube (lambda (x) (expt x 
3)) when other dialects of Lisp will let you suppress the 
lambda by writing (define (cube x) (expt x 3)), don't despair. 
Scheme also allows the alternative syntax. I am avoiding the 
alternative syntax because it obscures the distinction between 
thé anonymous procedure and the name of the variable in 
which it is stored. 

Since procedures are first class citizens, they can be 
returned as the results of calls to other procedures. The power 
procedure defined below takes an argument y and returns an 
anonymous new procedure. The new procedure takes an 
argument x and returns x raised to the y-th power. 


>>) (def ine power 
(lambda Cy) 
(lambda (x) 
Cexpt x y )))) 

power 

>>> (power 3) 

8? PROCEDURE? 

>>> (map (power 3) '(1234 

(Ø 1 8 27 64 125 216 343 512 729 

>>) (map (power .5) '(01234 

(0.0 1.0 1.41421 1.73205 2.0 
3.82843 3.0 3.16228) 


96789 10») 

1000) 

96789 105) 

2.23607 3.44949 2.64575 


The cube procedure could have been defined using power. 


>>> (define square (power 2)) 

Squere 

>>> (map square ' (012 3456789 10X0 1 444 9 16 
25 36 49 64 81 100) 

Since procedures are first class citizens, we can create a 
list of anonymous procedures that will raise their argument to 
one of the powers 0 through 10: 


>>> (map power '(Ø 12345 6789 10) 
(8«PROCEDURE» — "«PROCEDURE? — «PROCEDURE?  #<PROCEDURE> 
8 PROCEDURE» 8 «PROCEDURE» 8 (PROCEDURE? 8 <PROCEDURE> 


«PROCEDURE» *«PROCEDURE» ®<PROCEDURE> ) 
We can apply every procedure in that list to the integer 2: 


>>> (map (lambda (f) (f 2») 
(map power ' (012345678 9 100)) 
(1248 16 32 64 128 256 512 1024) 


I hope that this extremely simple and artificial example 
has suggested the new programming styles that become 
possible when a language treats procedures as first class 
citizens. The possibilities are both liberating and dizzying. 
There is no reason to be fancy for the sake of fanciness, but it 
is often true that intelligent use of first class procedures will 
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simplify an otherwise intimidating program. 

So far none of the examples have used any assignment 
statements. Assignments are used far less often in Scheme 
and Lisp than in mainstream programming languages like 
Pascal It is quite practical to write major programs in 
Scheme without using a single assignment statement. Such 
programs are said to be written in the functional style. When 
a program is written in the functional style, every procedure 
can be specified entirely by the relationship between its 
arguments and its results. In the absence of assignments (and 
other side effects such as I/O), that relationship is a simple 
mathematical function -- it never changes. 

Object-oriented programming, as  epitomized by 
Smalltalk, relies heavily on assignments to change the 
internal state of objects. Scheme currently provides no special 
support for object-oriented programming, but first class 
procedures can serve as objects with internal state. 

Consider the problem of implementing a counter in 
Pascal as part of a simulation program. We could use a global 
variable as the counter, but that would make it hard to add new 
behavior to the counter later on. (For example, we might 
want to animate the counter in some way, so the counter 
should update the display every time it is incremented.) It 
would be better to implement the counter as a procedure. In 
Pascal, unfortunately, the state of the procedure must still be a 
global variable, as in the following Scheme code. 


>>) (define n 0) 
n 
>>> (define counter 
(lambda () 
(set! n C+ n 1D 
n2) 
counter 
>>> (counter) 
1 


>>> (counter ) 
2 

2?) (counter) 
3 


>>> (counter) 
)»»n 


3 

One problem with using a global variable to hold the 
state of the counter is that we are likely to forget about it and 
then try to use a global variable with the same name for some 
other purpose. If we are lucky the compiler will complain. If 
unlucky, we will also forget to declare the other variable and 
will have a hard time finding out why the program won't 
work. 

One reason we might forget to declare the other variable 
is that in Pascal the declaration, initialization, and use of a 
global variable are so widely separated. Ideally the state of the 
counter procedure should be a variable that is visible only 
within the procedure, is declared near the procedure, and is 
initialized near the procedure. We would like to have a syntax 
very much like: 


>>) (define counter 
(let (Cn 00) 
(lambda () 
(set! n (+ n 10) 
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n))) 

counter 

This actually works in Scheme. The (let ((n 0)) ...) 
syntax introduces a new variable n whose initial value is 0. 
The new variable is visible only within the lambda 
expression, and the value of that lambda expression -- an 
anonymous procedure -- is the value of the let expression. 
There's nothing special about the let expression; though 
Pascal has no equivalent, the let expression is roughly the 
same as block in Algol 60 or some of the newer C compilers. 
What's special is the lambda expression, because it evaluates 
to a first class procedure and first class procedures remember 
their non-local variables: 


>>) (counter) 
1 
>>) (counter) 


2 
2>) (set! n 837) 
837 : 
»»» (counter) 


>>) (counter) 

4 

As the assignment to n shows, the local state of the new 
counter procedure has nothing to do with the global variable n. 

Suppose our simulation requires hundreds of counters. 
We could write hundreds of counter procedures, but then any 
change in the behavior of a counter would require us to change 
hundreds of lines of code. Why not write one procedure that 
creates new counter procedures? While we're at it, we'll make 
the initial state of the counter be a parameter to the procedure 
that creates counters. 


>>) (define make-counter 
(lambda () 
(lambda (2 
(set! n C+ n 1)) 
n))) 


make-counter 

>>) Cdefine c1 Cmake-counter 108)) 
c1 

»»> (define c2 Cmake-counter 
c2 


The local states of c1 and c2 are independent, because a 


new variable named n is created every time make-counter is 
called. 


-5000)) 


2>) (c1) 
101 

))» (c1) 
102 

>>) (c1) 
103 

>>>) (cl) 
104 

>>) (c2) 
-4999 
))» (c2) 
-4998 
»)» (c2) 
-4997 
)) (cl) 


We have seen how to use first class procedures to 
implement objects with local state. The object we've been 
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using as our example has a very simple behavior, however. 
What if there were several distinct operations on the object? 
One way to implement distinct operations is through message 
passing, which is similar to the way Smalltalk does it. 

The code below introduces some new syntax. The case 
expression should be understandable. The (lambda (operation . 
args) ...) syntax is used to create a procedure that takes one or 
more arguments. The value of operation will be the first 
argument to the procedure, and the value of args will be a list 


of any remaining arguments. The car procedure extracts the 
first element of a list. 


>>) (define make-counter 
(lambda (n) 
(rec self 
(lambda Coperation . 
(case operation 
CCcount) (set! n C+ n1) n) 
CCreport) n) 
(Creset) (set! n (car args?) 


args) 


n) 


(else Cerror “Bad operation 


on counter" self 
n))))))) 


make-counter 

>>) (define c3 Cmake-counter 49)) 
c3 

>>) (c3 ‘count) 

41 


>>> (c3 'count) 
>>> (c3 'report) 
>>> (c3 ‘count) 
))) (c3 ‘reset 1000) 
>>> (c3 'report) 
2>) (c3 'count) 


299 Cc3 'count) 


Message-passing isn't the only way to implement objects 
with complex behaviors. It is sometimes more efficient to 
create a new procedure for each operation on an object. The 
make-counter procedure shown below returns a vector of three 
procedures. 


>>) (define make-counter 
(lambda (n) 
(vector 
(rec count-method 
Clambda (€) (set! n C+ n 12) n D 
(rec report-method) 
Clambda (D) n2) 
(rec reset-method 
(lambda Cnew-value) 
n))))) 


(set! n new- 
value) 


make-counter 

>>) (define c4 (make-counter Ø) 
c4 

)»» c4 

8(98 «PROCEDURE count-method? 
8«PROCEDURE  report-method» 


8«PROCEDURE reset-method> ) 
Scheme vectors are accessed using zero-origin addressing, 
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so element 0 of the vector is the procedure corresponding to 
the count operation. 


))) (vector-ref c4 Ø) 

8«PROCEDURE count-method» 

The count operation takes no arguments. In Scheme we 
call a procedure of no arguments by enclosing it in 
parentheses: 


))) ((vector-ref c4 0)) 
1 
»»> CCvector-ref c4 0) 
2 
>>> CCvector-ref c4 0) 
3 


>>> ((vector-ref c4 9) 

4 

Element 2 of the vector corresponds to the reset 
operation. It takes one argument: 


>>> Cvector-ref c4 2) 

" «PROCEDURE reset-method> 

>>> ((vector-ref c4 2) -100) 

- 100 

))) ((vector-ref c4 0)) 

-99 

>>> ((vector-ref c4 0)) 

-98 

)5) 

The counter examples have shown that two features of 
object-oriented programming -- local state and message 
passing -- are provided for in Scheme without any special 
machinery, simply because procedures are first class citizens. 
Two other features of Smalltalk, namely inheritance and 
dynamic redefinition, can also be programmed in Scheme, but 
they are complicated enough to justify special machinery as in 
Smalltalk. 

Numbers and procedures are not the only first class 
citizens of Scheme. Every Scheme value is first class. This 
is the ideal. Very few current programming languages achieve 
it. 
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Correction! 

A couple of months ago we reported the capacity of cons 
cells the MacScheme environment can produce. Those 
numbers were slightly incorrect. Using a 512K Mac one may 
get 10,000 cons cells. With a 2 megabyte mac one can get 
over 100,000 cons cells. 

MacScheme comes with a small spiral bound book 
containing the reference manual, while it is not intended to be 
a major reference for the language, it is very informative. 
Macsheme contains a debugger which allows the user to gain 
specific access to the "heap". When a procedure cannot be 
evaluated due to a mistake or typo, MacScheme goes to the 
debugger automatically. The user then analyzes the code using 
the debugger commands which are displayed after the debugger 
is entered. The user can turn this feature off if they want to. 
Parenthesis matching is done when entering the right side 
parenthesis. The corresponding left side blinks in inverted 
video once. There are lots of other nifty features in the editor 
and compiler and we hope to discuss them more in the near 
future. 

MacScheme, we are told, has already been chosen as the 
standard Macintosh Lisp environment for the Computer 
Science departments of at least two major universities. The 
users at these schools have logged thousands of hours of use 
with only one (!) intentional bomb. 

It is very ironic situation. MacScheme has what 
ExperLisp seems to be lacking, a somewhat object oriented 
environment, usable debugging facilities, a comparatively easy 
to get used to style of operation and best of all, extreme 
reliability. While ExperLisp allows the programmer to build 
windows, bunny and Quickdraw graphics, menu bars and all 
the other Mac (or Lisp Machine) like stuff into the 
programmers' product. These two environments will more 
than likely gravitate toward each other until they are complete. 
[ When will one product combine both features?? -Ed. ] 

ExperTelligence has been telling us since the release of 
ExperLisp that a developer's version will be released shortly 
(frankly, they should finish the current version first!!!). So far 
that hasn't happened and there seems to be no indication that it 
will. ExperTelligence seems more concemed with adding 
gimicks like Macintalk to ExperLisp. In the mean time 
Semantic Microsystems has told us that an add-on to 
MacScheme which will give access to Quickdraw is under 
developement. For the moment, I'd bet on MacScheme. [What 
about the rest of the toolbox? -Ed.] 

In coming months.. ExperOps5, NEXPERT (!) and 
more on Common Lisp procedures. F 
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This month, Mactutors' Lisp Listener has a special 
exClusive. In the first few installments of the Lisp Listener 
(nine months ago!) the question of how serious one can be 
when it comes to AI on the Mac was raised. This month we 
can be confident in saying that Mac can and is being used for 
developing real AI applications. Last summer the International 
Joint Conference on Artificial Intelligence (IJCAI) was the 
place for the unveiling of a relatively large number of AI 
related products for the Mac. These included ExperLisp version 
1.04, ExperOps5, MacProlog, Macscheme and as you will see 
in what follows the first serious end user expert system 
development application. John Roy has written for us a good 
description of what Nexpert is, what it does, and how it does 
it. 

PROGRAMMING IN NEXPERT 
by John Roy 


What are Expert Systems? 


In one sentence, expert systems are programs that imitate 
human reasoning. They recognize logical patterns that are 
similar to those recognized by humans, and then reason with 
them to produce expert-like performance. The term “expert 
system" should not be confused with "rule-based system" nor 
"production system". These latter two terms refer to 
implementation schemes, which are often used to build 
expert systems. 

The process of capturing expert reasoning is called 
knowledge engineering. Previously, the knowledge engineer 
had to analyze a domain of expertise and socraticly refine an 
expert system based upon that expertise until it performed as 
well as the human. Eventually, these knowledge engineering 
pioneers found that declarative (rather than procedural) 
programming paradigms are more appropriate when writing an 
expert system. 

LISP is used as the foundation of many expert systems 
because of its pattern matching, language extension, and data 
typing capabilities. These capabilities allow AI programmers 
to design declarative structures (which hold the expert's 
knowledge) and inference engines (which imitate the expert's 
logic). NEXPERT'’s AI Kernel was designed in LISP on a 
Symbolics "LISP Machine" before being ported to the 
Macintosh. 

What is NEXPERT? 


NEXPERT is a full blown rule-base development 
environment for serious knowledge engineering. It is the first 
rule-base development tool designed specifically for writing 
expert systems on the Macintosh. It uses if...then...do... rules 
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= John Roy 


exper lisp 


to represent the domain expert's knowledge. It has many 
sophisticated aids for rule-base development such as: 
automatic, graphical knowledge traces (better than those in 
KEE); automatic forward and backward chaining from the 
same rules (as in ART); an automatic dialogue system (as in 
PROLOG); an automatic explanation facility (How, Why, and 
Apropos); access to external data bases (those in SYLK form); 
and execution of external, compiled programs (such as those 
developed in C). 

It does not have a frame system, nor automatic belief 
maintenance. Not incorporating a belief maintenance system 
was a good idea, since no general theories are available, and 
each expert system must tailor uncertainty handling to the 
specific application. However, no frame system access means 
(1) no object oriented data structures, (2) no message passing, 
(3) no inheritance of attributes, and (4) instantiation of flavors. 
Frame systems concern design, maintenance, and manipulation 
of extremely large data bases. For applications where the data 
base management system already exists, or for which the data 
base is small (less than 1000 data values), or for which there 
is a simple taxonomy, the external SYLK file access and 
external program execution can easily be used to interface and 
manipulate the applicable data bases. 


Enough introduction, let's get down to business. 


ibis n 


p" rj 
If. 
There is evidence of: 
Boss-Called 
xf Emergency 
is NO 
And There is evidence of: 
Day time 
Then Work 
is confirmed as a likely conclusion. 
And ((Miles-To-Work) /45.00)*Time 
is assigned to ETA 


TT 1- NEXPERT Rule Editor 
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Basic NEXPERT Programming. 


The Rule Editor, shown in Figure 1, is where you view 
the rules and choose what operation to perform. By clicking 
on the dog-ear, the pages can be flipped forward and backward. 
The rules are alphabetically indexed by Hypothesis (which is 
how the buttons on the right allow rapid movement through 
the list). It is a bit difficult to understand the rule-base as a 
whole from only viewing one rule at a time, but the Network 
discussed later gives the rule-base developer a global view. 
There are similar windows (called Notebooks) for the Data List 
and the Hypothesis List. Selection of a rule-base operation is 
made by clicking on one of the icons at the bottom of the 
Rule Editor. From the left they are; (1) create a new rule, (2) 
modify the current rule, (3) create a new rule by copying the 
current rule, (4) delete the current rule, and (4) save the 
knowledge base. 

I've found that creating a new rule by copying a similar 
one, is the best way to go, particularly since all of the rule 
conditions are ANDed together, and the only way to achieve an 
OR is to create another rule with the ORed condition modified. 
This is the same with OPSS, though OPSS has a 
MEMBERSHIP operator and NEXPERT does not. 


Once an operation has been selected what I call the rule 
template interface appears. This is the main development 
interface. One enters and modifies all of the rules from this 
rule template interface. All you need to do is fill in the 
conditions, the hypothesis, and the actions via the pop-up 
menus shown below. Note that currently only eight (8) 
conditions and actions can be used in a single rule (i.e. # of 
conditions + # of actions < 9). If the rule had more than 
eight, then two rules must be written such that they link 
together and fire in order. One of the nicest, and oddly 
important, capabilities available are COPY DATA and COPY 
HYPOTHESIS. These prevent the rule-base developer from re- 
typing, and more importantly, misspelling data and 
hypotheses. Note that NEXPERT is case sensitive, and does 
not allow spaces within the names given to data. 

I've pasted this window together so that all of the pop-up 
menus are visible at once. The basic rule template (underneath 
the three pop-up menus) consists of the IF slots, the THEN 
slot, the AND DO slots, and the CONTEXT slots. By 
clicking on a slot the appropriate menu will pop-up. Don't 
worry about the context slots right now, they are an advanced 
programming feature that allow the rule-base developer to 
Suggest knowledge island transitions, (fully explained in a 
future article, and needed only for extensive rule-bases). The 
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Figure 2 - The Rule Template 
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menu at the left shows all of the tests available to form rule 
conditions (see Table 1). The menu at the right shows all of 
the actions that can be performed (see Table 2). The menu in 
the middle (slightly covered by the other previously mentioned 
menus) is for entering arguments and equations. The COPY 
DATA and COPY HYPOTHESIS are available from this 
menu. 


Table 1 - Condition Tests 
CANCEL do nothing 
CLEAR clear test slot 
YES and NO test boolean 
>, <, 2, S, =, # Compare numeric equation to 
constant 


NAME declare global synonym 

IS and IS» compare multi-valued datum to 
constant 

RESET set datum to "unknown" 

EQUAL and 

UNEQUAL . compare two multi-valued data 

Table 1 - Action Operations 

CANCEL do nothing 

CLEAR clear operation slot 

DO perform numeric equation and 
assign to datum 

LET assign multi-valued datum a 
constant 

RESET set datum to "unknown" 

SHOW either type out a text file to the 
Apropos Window 
or pop-up a paint picture to fill the 
screen 

LOADKB append another knowledge base to 
current one 

EXECUTE perform external function 

RETRIEVE load data from an external SYLK 


file 


Once the rule has been entered the OK button will only 
darken if the rule is structured properly. Clicking on the 
CHECK button will highlight the offending slot. If the rule 
is properly structured, but a datum is misused (eg. using a 
previously defined boolean in an equation), a message will 
appear (after the OK button-click) explaining the problem. 
This is very nice most of the time but can be a pain if you 
decide that you would like to change the data type of a datum. 


NEXPERT has two basic values that any datum may 
have: NOTKNOWN and UNKNOWN.  NEXPERT uses 
UNKNOWN as the "reset" value. Whenever a datum's value 
is needed and it is currently UNKNOWN, then NEXPERT 
will switch to backward chaining to attempt to establish a 
value from the data already available. If this is unsuccessful 
then the user is queried, via the Question Window, for a value. 
NOTKNOWN on the other hand, is used to mean that the user 
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has been questioned and does not know the answer. 
NOTKNOWN allows default reasoning to be done and 
prevents NEXPERT from continuing to ask for a value that 
the user does not know. 


Knowcessing 


"Knowcess" is the term for the rule-based inferencing 
process. This is where NEXPERT's AI Kernel shows what it 
is made of. The process can be initiated by suggesting an 
hypothesis or volunteering a datum. One may also use a 
combination of the two. If any data is volunteered, then the 
system will drive forward, attempting to establish as many 
hypotheses as possible. You can control this forward chaining 
via NEXPERT's Strategies (see next NEXPERT article for 
when, why, and how this should be done) If one only 
suggests an hypothesis, NEXPERT will begin by looking 
backward in an attempt to find sufficient information that will 
prove this hypothesis. This information can lead the system 
to other hypotheses that need to be established, which can lead 
to others, which lead to others, etc. 

Once the system reaches a rule that has some 
UNKNOWN datum in it, the user will be prompted for a value 
(see the example in Figure 3 below). At this point the user 
can access the multi-level Explanation Facility (via the WHY? 
and HOW? Buttons ), which is automatically built from the 
static forward and backward chains already in the rule-base. 
Note that the system knows that the example datum BOSS- 
CALLED is a boolean and that the user may answer 
NOTKNOWN. The last button, Apropos, is for tailoring the 
System to the application even more. When any Apropos 
Button is clicked on, NEXPERT will bring up the file (text or 
pictures) that the rule-base developer has made for this datum. 
This is very useful for instructing the user about the meaning 
and use of a specific datum. 


= Question EE 


Is there evidence of: 
Boss -Called 


FRLSE NOTKNOIDN 
Explanation Facilities: 


Figure 3 - The Question Window 


There are other windows that allow the rule-base 
developer to watch the progress of the Knowcess. The 
Transcript Window keeps a complete record of the session, but 
it slows down the processing by a factor of eight. There is the 
option to turn the Transcript Window off, which I always use 
at run-time. The Hypothesis Window displays the hypothesis 
currently under consideration. And the Conclusions Window 
reports whether the hypothesis was rejected, established, or 
underdetermined. But the best way I have found to debug a 
rule-base is to get a global view. 

As I said before, the way to get a global view is from the 
Network. This is an automatic, dynamic, graphical knowledge 
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trace. Figure 4 shows NEXPERT in the middle of the 
KNOWCESS process. The dynamics of the system can be 
followed by noting (a) in this example, the datum TIME 
points to the hypotheses DAYTIME, NOON, and WORK, (b) 
that DAYTIME and NOON have already been established, (c) 
that the system is considering the hypothesis WORK, and (d) 
that it is currently prompting for the value of the datum BOSS- 
CALLED (see arrow and bulls-eye in the lower left corner). 


Using the operation icons on the left, the rule-base 
developer can "navigate through the knowledge islands." The 
functions called by these icons allow investigation of only 
those areas of the knowledge graphic that are currently of 
interest. From the top, the operation icons are: (1) single or 
multiple knowledge island display, (2) display data that point 
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a A-Sunny-Noon? YES-IT-SU 
Sun-Status Is OUTV/—— —r2 


inp Yes Boss- Called 
Emergency Is YES D 5 


to this hypothesis, (3) display hypotheses that this datum 
points to, (4) erase this link, (5) focus attention on this datum 
or hypothesis, and (6) apropos this datum or hypothesis. 
These operations only affect the display, not the actual 
knowledge graph of the rule-base. From this one window all 
of the rules can be viewed, all of the links between rules can 
be checked, and the dynamics of the Knowcess process can be 
monitored; making it an excellent aid in the debugging of a 
rule-base. 

Overall, the programming environment of NEXPERT is 
very clean and efficient. In the next article on NEXPERT I'll 
be addressing the more complex issues of the AI Kernel, 
Controlling the Agenda, Customizing the User Interface, 
Speeding-Up Execution, Outside Database Access, and of 
course a Full Bug Report. e 


Windows 


itn 


Figure 4 - TheNetwork 
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Al Applications 
Debugging in Lisp 


[Since the last discussion on Macscheme, Semantic 
Microsystems has updated their product. They are currently 
shipping version 1.1 which includes access via Macscheme 
primitives to the Quickdraw routines in ROM. Version 1.1 is 
also compatible with The Mac+ and HFS. Registered owners 
of earlier versions can update by sending $20 and their original 
MacScheme disk to Sematic Microsystems. Additionally, 
Semantic Microsystems announced the first part of a new 
development system called Macscheme+Toolsmith. This 
product includes Pascal-like access to the Toolbox routines in 
ROM from Macscheme. It also allows the programmer to 
design an apparently free standing application without the 
MacScheme environment. A minimized run time system will 
be required, however, the application and the run time system 
may be sold without royalties to Sematic Microsystems. 
Macscheme+ToolSmith will be sold at $250, while 
Macscheme is still $125 (Which makes us wonder, why $20 
for the update?!). We've been pleased with the MacScheme 
product and the developers’ responses to help requests. This 
month we feature a simple description on using the debugger 
in MacScheme. - Andy Cohen, A.I. Contributing Editor] 

Debugging in Lisp 
b 


Anne Hartheimer 
Semantic Microsystems, Inc. 

Most Lisp systems include good debugging tools, in part 
because Lisp has traditionally been an interactive, interpreted 
language. I am going to explain the sorts of debugging tools 
that are typically provided by Lisp systems, how to take 
advantage of them and, in particular, how to use the debugging 
aids provided by the MacScheme Lisp system. 

What kinds of debugging help can a system give you? 
For starters, it can tell you that an error exists. It can also 
help you find the error that it has told you about. Of course, 
it can't detect all errors. For example, only you can tell if 
your program is doing the right thing or generating the output 
you desire. However, if you know that a program produces 
the wrong output, or at least questionable output, a debugging 
tool can help you figure out why. Once you have located the 
source of the error, Lisp debugging tools can help you fix 
your buggy program and test it conveniently. 

There are several standard debugging tools. Compile- 
time and run-time error checks discover errors. Inspectors let 
you examine the scene of the crime. If you suspect that there 
might be something wrong with a particular procedure, then 
tracers, steppers, and the ability to insert breakpoints in a 
program can help you see what is happening as the program is 
executed. Lastly, editors and incremental compilers can make 
it easy to modify small parts of your program and move on to 
the next bug. (One of the reasons Lisp interpreters are popular 
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MacScheme 


Lisp 


Andy Cohen 
Al Contributing Editor 


is that they give you incremental compilation for free.) 

MacScheme has all of these tools except a stepper. I'll 
be using MacScheme in the examples that follow. 

Compile-time Checks 

Error checks can be performed at compile-time or at run- 
time. A compiler checks for illegal syntax and some kinds of 
domain errors. (Compile-time checks for domain errors are 
usually called type-checks.) In MacScheme, when a compile- 
time error is detected, it is reported and the system performs a 
reset. For example, if is a reserved word, so it is not legal 
syntax to assign to it: 


>>> (set! if 3) 


ERROR: Keywords of special forms may 
not be used as variables 
(set! if 3) 


If a procedure is known to the compiler, then the 
compiler can make sure it is given the right number of 


arguments. This is an example of a compile-time domain 
check. 


»»» (cons 3 4 5) 


ERROR: Wrong number of arguments to 
integrable procedure 
(cons 3 4 5) 


MacScheme, like most Lisps, performs very few compile- 
time domain checks. This is because Lisp associates types 
with run-time objects instead of with variables, so compile- 
time checking is not possible in general. This puts Lisp at a 
disadvantage compared to Pascal because run-time domain 
checks are performed only on the pieces of code that are 
actually executed. If you have a program that contains several 
branches, you can not be sure that it is free of domain errors 
until you test each of the branches. In Pascal, on the other 
hand, many domain errors are caught at compile-time, placing 
less of a burden on testing. Lisp must make up for this 
disadvantage by having excellent run-time domain checking. 

Run-time Checks 

Interpretive Lisp systems excel at run-time error checks. 
An interpreter will detect undefined variables and domain errors 
such as passing the wrong number of arguments to a 
procedure, using a non-procedural object as a procedure, 
attempting to add two strings, etc. Most systems interrupt 
execution, print a helpful error message on the screen, and 
place you inside an inspector so you can examine the context 
of the error. This is a far cry from a core dump or a bomb 
window. 

The following example is from page 72 of The Little 
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Lisper. vec+ is a function which takes two vectors and 
returns the vector that is their sum. (The Little Lisper 
represents vectors as lists instead of using Scheme's built-in 
vector data type.) 


))» (define vect 
(lambda (vec! vec2) 
Ccond 
CCnull? vecl) CDD 
(t (cons 
(+ (car vec1) (car vec2)) 
Cvec+ (cdr vec!) 
(cdr vec2))))))) 
vect 
))) (vect '(84 5) '(11 1D 
(456) 
>>> (vect '(12 3 4) '(0 25) 


ERROR: Bed argument to cdr 
( 


Entering debugger. Enter ? for help. 


Oops! Let's track down the cause of this error message. 
We first ask for the name of the procedure in which the error 
occured. 


debug:? i , i| means "identify procedure" 
vect 


So the error occurred in our vec+ routine. Let's look at 
the code for vec+. 


Q0 0UAM 
4 


debug:? c c" means "show code" 
(lambda (vec! vec2) 
(cond €(null? vec1) €) 
Ct 


(cons (+ (car vec1) (car vec2)) 
Cvect (cdr vec!) 
(cdr vec2)))))) 


Since the error message told us that cdr was passed a 
bad argument of (), we should think about the calls to cdr 
in vec+. (In Scheme, cdr is defined only on non-null lists. 
When applied to a non-null list, it returns a list consisting of 
everything in its argument except the first element.) Let's 
check out the values of vec1 and vec2 since these are the 
two possible arguments to cdr that could be causing the 
error. 


debug:? a ; "a" means "all variables" 


vecl = (3 4) 
vec2 = () 

So vec2 is the problem. Looking more carefully at the 
code, we can see that we're testing to see if vec1 is null but 
not vec2. We need to add a test for vec2. 

Inside the MacScheme debugger you can find out the 
name of the procedure in which the error occurred, the 
arguments that were passed to that procedure, the variables 
accessible at that point and their values, and the chain of 
procedures awaiting results. You can move back to the 
context of any procedure awaiting a result and look at the 
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variables that are accessible to that procedure. You can 
evaluate arbitrary expressions in the environment of any of the 
procedures along the chain. You can modify arguments passed 
to those procedures, and then resume computation. You can 
modify the values of variables and procedure definitions within 
the environments of any of the procedures along the chain and 
resume computation. In addition, you can exit the 
MacScheme debugger, perform some other computation, and 
then decide that you want to do additional inspecting of the 
last bug you encountered. You can reenter the debugger and be 
back in the state of the most recent error. 
Breakpoints, Tracers, and Steppers 

Let's shift gears now, and consider the following 
situation. Suppose your program is producing incorrect 
output. The traditional approach is to insert print statements 
in it. The problem with inserting print statements is that it is 
difficult to know what information to print, and if you print 
too much the information is unwieldy. It is better to insert 
breakpoints into your program. In MacScheme, when 
(break) is evaluated, execution is interrupted and you are 
placed in the MacScheme debugger. You can now use the full 
power of the inspector to examine the context of the 
breakpoint. Instead of having to decide at compile-time what 
features will be of interest (as you had to do when you 
debugged by inserting print statements), you get to decide 
interactively what to look at. For breakpoints to be really 
useful, your inspector must let you resume the computation. 
Then you can move on to the next breakpoint that you have 
set if you decide that things look just fine in the context of the 
first breakpoint. 

It's also useful to be able to induce a break manually to 
snoop around in computations that seem to be taking a long 
time or acting weirdly. MacScheme lets you do so by 
selecting Break from the menu. This interrupts a computation 
and places you in the MacScheme debugger. When you have 
finished looking around, you can type an "r" to resume the 
computation. 

If you suspect that a particular routine embedded in your 
program is producing bad outputs or receiving bad inputs, a 
convenient way to test your hypothesis is to trace the routine. 
Whenever a traced routine is called, the MacScheme tracer 
prints its name and the arguments it was passed. When the 
routine returns, its name and the value it returns are printed. 


>>) (define (fact n) 
Cif (zero? n) 
Ü 
(* n (fact (- n 10200) 
fact 
>>) (fact 3) 
Ü 
>>> (trace fact) 
#! true 
>>) (fact 3) 
Computing CÓ PROCEDURE fact? 3) 
Computing CÓ PROCEDURE fact» 2) 
Computing (®<PROCEDURE fact? 1) 
Computing CÓ PROCEDURE fact» 0) 
(8«PROCEDURE fact? 8) --> Ø 
(8«PROCEDURE fact? 1) -— Ø 
(«PROCEDURE fact? 2) - Ø 
(8«PROCEDURE fact? 3) -— Ø 
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Here we see that the recursive calls are passing the correct 
arguments, but the wrong results are returned. 

Once you have determined the problem to be a routine 
that is receiving good inputs and producing bad outputs, and 
you have little idea why, you might want to step through the 
procedure to see what is going wrong. A stepper allows you 
to view the evaluation of each subexpression of a routine as it 
is happening. Some steppers let you use the full power of the 
inspector at each step along the way. You can view a stepper 
as the ability to insert breakpoints automatically between 
every expression of your program. A stepper is the one tool 
I've mentioned that MacScheme doesn't have. To explain why 
MacScheme does not have a stepper, we must look at the 
interaction between compiling and debugging. 

Interpreters and Compilers 

Interpreters are best for development and debugging 
because they work with the source code, which programmers 
understand. Compilers turn nice, readable source code into the 
gobbledygook of machine language—but that machine 
language sure runs fast. Most Lisp compilers also give up 
some run-time checking in order to get more speed. One of 
the main advantages of special-purpose Lisp machines over 
comparably priced conventional computers is that Lisp 
machines have special hardware to perform run-time checks 
very quickly. 

MacScheme, like Smalltalk-80, uses a compromise. It 
compiles to byte code—the machine language for a 
hypothetical Lisp machine—and then interprets the byte code. 
This approach gives most of the speed of compiled code 
together with most of the nice debugging associated with 
interpreted code. The byte code is also more compact than 
either native code or source code if the source code is discarded 
after compilation, but MacScheme normally keeps the source 
code around to aid in debugging. 

Though MacScheme keeps the source code for each user- 
defined procedure, it does not try to remember the 
correspondence between individual byte code instructions and 
source code subexpressions. There just isn't enough memory 
on a Macintosh to maintain the large tables that would be 
necessary, which is why MacScheme doesn't have a stepper. 
Smalltalk-80, on the other hand, does something very clever. 
Whenever you run its stepper, Smalltalk constructs those 
tables incrementally, by de-compiling the byte code if 
necessary. 

Texas Instruments’ PC Scheme for the IBM PC and TI 
Professional also uses byte code. Compared to MacScheme, 
PC Scheme emphasizes speed at some cost to debugging. For 
example, PC Scheme normally does not retain source code. 
Because the PC is slower than the Mac and can address less 
memory, this is a reasonable engineering compromise. 

Conclusions 
No set of debugging tools can make debugging easy, but 
they certainly can make it easier, faster, and more fun. We've 
looked at the help provided by compile-time and run-time error 
checking, inspectors, breakpoints, tracers and steppers. These 
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tools were first developed for Lisp systems in the 1960's, yet 
are still hard to find in other languages. Lisp's supportive 
programming environment is one of the main reasons why so 
many Lisp programmers are fanatical about their favorite 
language. 
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How to Turn Off the Debugger 
If the automatic placement into the debugger is confusing 
Or it is just a pain to you, try the following procedure sent to 
us by the folks at Semantic Microsystems: 


jj) (debugger *!false) turns off the debugger. 

jj; (debugger #!true) turns on the debugger. 

jj) (debugger) returns ®!true if the debugger is on, 
jj; Otherwise it returns *!false 


(def ine debugger 
(let (Cstate #! true) 
(real-debug debug) 
(fake-debug Clembda args (reset2))) 
(lambda flags ; flags is a list of arguments 
(if (null? flags) 
state ; no arguments 
(begin 
(set! debug Cif (car flags) real-debug fake- 
debug) ) 


(set! state (car flags?) 
state))))) 
Corrections 
A couple of typos from the last column on MacScheme 
were identified by the author. The first was in one of the code 
samples using sort. The following is the correct code: 


2>) (sort '("Even" “mathematicians” "ere" "accustomed" "to" 
"treating" "functions" "as" "underprivileged" 
"objects") 
(lambda (x y) 
Cor (<? Cstring-length x) (string-length y)) 
Cstring<? x y)))) 


("as ...) 

The second error was in the code defining the procedure 
make-counter. The code should have included the argument n 
as follows: 


(define make-counter 
(lambda (n) 
(lambda C) 
(set! n C+ n 10) 
n))) 


There was also an error in the third reference. The reference 
was supposed to read Joseph Stoy's Denotational Semantics of 
Programming Languages. Our thanks to Will Clinger of the 
Tektronix Computer Research Laboratory (and also of 
Semantic Microsystems). 
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Lisp Listener 
Simple Graphics Objects 


Graphics Objects In MacScheme 

Welcome back to Lisp Listener! Our current choice of 
Lisp implementations is MacScheme by Semantic 
Microsystems. Scheme is a modern and elegant dialect of 
Lisp, and MacScheme is a robust, complete, and elegant 
implementation. Previously MacScheme did not offer pro- 
grammers much access to the Macintosh toolbox. In August 
a new release of a product called MacScheme + Toolsmith, 
was made which allows the production of event-driven 
programs. This will be followed shortly by an application 
builder that will make it possible to create stand-alone 
applications with MacScheme. The MacScheme editor, which 
is currently fairly limited, is also in the process of being 
upgraded. Look for reviews of all these items in future 
columns. 

The only way to get to the toolbox in the previous incar- 
nation of MacScheme, version 1.11, was through an escape 
into machine language that looks very complicated (I haven't 
tried it out). Version 1.11 does, though, have some simple 
graphics capabilities which we will be using in this month's 
column. As it stands now, MacScheme is a great way to learn 
Lisp and explore object oriented programming. 

Graphics in MacScheme 

In early 1986, MacScheme was enhanced to allow the use 
of simple graphics operations. MacScheme has one graphics 
window, which must be opened with a procedure call before 
graphics can be used. The graphics window can be two sizes, 
‘full’ or ‘half’. To open up a small graphics window, the code 
would be: 


(stert-grephics ‘half ) 


Once a graphics window is open, you can get rid of it by 
saying: 


Cend-graphics) 


(One thing to be careful of: you aren't allowed to 'start- 
graphics’ if the graphics window is already there, and you 
aren't allowed to end them if it isn't there. Moreover, there is 
currently no way for a procedure to test whether the graphics 
window is open. Hopefully Semantic Microsystems will add 
this test feature soon, or just allow you to open the window 
even if it already open, or close it if it is closed.) 

Once the graphics window is open, there are just under 30 
commands for drawing in it. These are all pretty basic: 
drawing, erasing, and inverting lines, rectangles, ovals, circles 
and points. You can also set up a picture that will be 
refreshed if the graphics window is obscured, draw a string, and 
Clear the window. 
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For Macintosh programmers, MacScheme graphics take a 
little readjusting. This is because MacScheme uses the 
coordinate system that you learned in grade school, instead of 
the one you learned in /nside Macintosh. That's right, the x 
coordinate comes first, followed by the y coordinate. The half 
size graphics window is 470x130 pixels, so the procedure call 


(paint-oval 20 95 58 125) 


would paint a circle in the lower left hand corner of the 
graphics window. 


The general form of graphics procedures that work with 
two points is 


(procedure xi y1 x2 y2) 


Data Abstraction 

This brings us to the first programming issue of the 
column: data abstraction. As you can imagine, it would be 
awkward working with rectangles and points if you always had 
to think about them in terms of their individual coordinates. 
One of the strong points of Lisp is its ability to create 
complex data objects. So, before I did anything with graphics, 
I created a set of procedures for working with points and 
rectangles. The simplest way to work with a rectangle is to 
set it up as a list of four coordinates. The coordinates can then 
be passed to a MacScheme graphics procedure by saying 


(apply the-procedure the-list ) 


In the sample procedures shown here, I use a slightly 
more complex data structure because it makes the issue of data 
abstraction stand out more clearly. 

As I have defined them, a point is a simple pair, and a 
rectangle is a list of points. But the particular internal 
Structure of a point or a rectangle is unimportant to most of 
the procedures I will write. When I want to work with a point 
or rectangle, I always do so with the selectors and 
constructors that I have created. I use a constructor to create a 
rectangle or point, and I use a selector to get information 
about a rectangle or point. The selectors and constructors are 
the only parts of the system that need to know what the 
internals of the data structure look like. Once you have a 
complete set of selectors and constructors, you can forget 
about the underlying structures which the selectors and 
constructors use to work with the data. This technique is 
called data-abstraction, and is very useful for keeping programs 
as simple as possible. For example, the procedure adds-points 
knows nothing about points besides the fact that they have an 
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x and a y coordinate. If I change the way I store points, I need 
only modify the selectors and constructors; the rest of the 
program remains the same. 

Now that we have a way of storing points and rectangles, 
we need a way of passing rectangles to Scheme graphics 
procedures. Because a rectangle is defined by two points (as 
all Macintosh programmers know), we can use the rectangle 
data form for any procedure that requires two points (i.e. four 
coordinates) as arguments. The result is the procedure 2-point- 
function. This procedure takes two arguments, a graphics 
procedure and a rectangle, and it calls the graphics procedure, 
giving it the coordinates from the rectangle as arguments. 2- 
point-function also illustrates the ease with which procedures 
can be passed as arguments in Lisp. 

An additional feature of Lisp should be clear by now: 
Lisp programs are not constructed as single units, as are 
programs in other languages. Rather, procedures are defined, 
thereby adding to the procedures which come already defined in 
the language. A Lisp program is little more than the 
interaction of a number of procedures. The result is an 
extensible working environment, similar to that found in 
Forth. 

Object oriented Programming 

The next feature of Lisp we will discuss is the ease with 
which procedures can return other procedures. Every procedure 
in Lisp, when evaluated, returns something. For example, (+ 
4 3) returns 7, and (car ‘(a b c)) returns a. In Lisp it is very 
easy to have a procedure return another procedure as its result. 
Here is a simple (though fairly useless) example, a procedure 
which churns out procedures to add a constant to a number. 


(define (make-adder the-constant) 
Clambda (the-input-var iable) 
(+ the-constant 
the-input-var iable))) 


The procedure make-adder returns a procedure (a lambda 
expression) which takes a single argument, the-input-variable. 
If we say, 


(set! addfive (make-adder 5)) 


we have a new procedure, called addfive, which will add 5 
to any number it is given as an argument. 

One of the most powerful features of Scheme is that it is 
lexically scoped. This means that variables within a procedure 
are scoped according to the environment in which the 
procedure is defined (as opposed to dynamic scoping, in which 
variables are scoped according to the environment from which 
the procedure is called ). In the example given above, the 
procedure addfive works because the variable 'the-constant' is 
scoped according to the environment in which addfive was 
defined. When addfive was defined, the-constant was equal to 
5. As far as addfive is concerned, the-constant will always be 
5, even if we call make-adder again and again, giving it a 
different number each time, and even if we call addfive from 
another procedure that has a variable called 'the-constant' with 
a different value. 
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When you put together lexical scoping and procedures 
returning procedures, you get the ability to do object oriented 
programming. In case you don't know it as more than a buzz- 
word, heres a brief description of object oriented 
programming. 

In older forms of programming, data and procedures are 
stored separately. You have a bunch of data, and then you 
have the procedures that operate on the data. (What would 
Von Neuman have thought of this!?) In our rectangle example 
above, we would define a bunch of rectangles, and then we 
would have procedures that would do something to one or 
another of the rectangles. In object oriented programming the 
procedures and data are bundled together. Instead of having a 
procedure make a rectangle get bigger, you just send a message 
to the rectangle, telling it to make itself bigger. Or you tell 
the rectangle to move, or draw itself, or whatever. Because 
procedures in MacScheme are lexically scoped, they can have 
internal state. The internal state is the data within the object, 
and the rest of the procedure knows how to operate on this 
data. Object oriented programming has advantages that are 
similar to the advantages of data abstraction. Once you define 
an object, you can forget about how its insides work. You 
just treat it as a black box and work with it as a single unit. 
When you want it to do something, you tell it what to do; 
when you want to know something about it, you ask it. The 
creation of objects helps keep programs modular and simple. 
You work on small, easily understood units which you can 
then assemble into larger units, and so on. 

The first objects we will be working with are ovals. You 
give the procedure make-oval a rectangle or any combination 
of points and coordinates, and it returns a procedure which is 
an object that can draw, erase, invert itself, tell you its 
bounding rectangle, or receive a new bounding rectangle. 
Because this object is a procedure, you call it just like you call 
any other procedure. The argument that you give it is called 
the ‘message’ which you send to the object. It is up to the 
object to decode the message and act accordingly, or signal an 
error if it doesn't know what to do. 

The next stage of object oriented programming involves 
something called ‘inheritance’. Inheritance occurs when one 
object takes on the characteristics and abilities of other 
objects, usually adding new abilities of its own. This month 
we will keep thing simple and just discuss single inheritance, 
that is, we will define an object that inherits from one other 
object. 

When you call the procedure make-grow-oval, you give it 
a bounding rectangle as an argument. Make-grow-oval then 
sends this bounding rectangle to make-oval, and gets back an 
object, an oval. It then returns a new object, a grow-oval, 
which contains this recently (and completely locally) defined 
oval. When you send a message to a grow-oval it first checks 
to see if it recognizes the message, in which case it does the 
appropriate processing. If it doesn't recognize the message, it 
passes it directly to its oval (i.e. it lets it ‘fall through’ to the 
internal object). In this way a grow-oval can add new 
functionality to an oval without losing any of an oval's 
standard features. One other interesting thing to note: the 
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grow-oval lets the oval take care of bookkeeping the current 
bounding rectangle. Whenever a grow-oval needs to know the 
bounding rectangle, it just asks its oval for the information. 
Doing It Together 

Anyone interested in learning Lisp should read Structure 
and Interpretation of Computer Programs by Hal Abelson and 
Gerald Sussman. This is not only a great book on computer 
programming, but it is all done in Scheme. The reference 
manual for MacScheme is also very well written, if you just 
want see what a particular command does. One other book on 
Scheme that Semantic Microsystems recommends is The 
Little Lispers, but I haven't seen it myself, and so I can't 


speak for it. 
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fine | MacScheme™ Top Level 

let (q >>> Cstart-graphics ‘hal f) 
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>>> Coval-samp ler) 

Cele *! true 


Program file 


Andrew Shalit 

3 Sacramento St. 
Cambridge, MA 02138 
(617) 498-6637 

June 7, 1986 


53,8 program that demonstrates graphics and 

jj jobject oriented programming in MacScheme 1.11 
,,,copyright 1986, MacTutor Magazine 

»,, written by Andrew Shalit 
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(cons x (car y)))) 
;;@ rectangle is a list of two points: (x1. y1) O2. y2)) 
(define (make-rect first-coord . other-coords) 
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Cif (rectangle? first-coord) 
first-coord 
Clet (Cfirst-other (car other-coords))) 
Cif Cpoint? first-coord) 
(list first-coord 
Cif Cpoint? first-other ) 
first-other 
Capply make-point other-coords))) 
Capply make-rect 
(cons (make-point 
first-coord first-other) 
(cdr other-coords))))))) 


,Selectors for getting coordinates out of points and 
rectangles 
(define (x-coord point) 
(car point)) 
(def ine Cy-coord point) 
(cdr point)) 
(define Cleft-top rectangle) 
(car rectangle)) 
(def ine Cright-bottom rectangle) 
(cadr rectangle)) 
(define Cleft rectangle) 
(x-coord Cleft-top rectangle))) 
(def ine (top rectangle) 
(y-coord Cleft-top rectangle))) 
(def ine Cright rectangle) 
(x-coord (right-bottom rectangle))) 
(def ine (bottom rectangle) 
(y-coord Cright-bottom rectangle))) 


,,tests to determine whether something is a point or rectangle 
(define (point? object) 
Cif (pair? object) 
(end — (number? (car object)) 
iss (number? (cdr object))) 


(def ine (rectangle? object) 
Cif (pair? object) 
Cand (point? (car object?) 
(point? (cadr object))) 


functions for adding and subtracting points 
(def ine Cadd-points point! point2) 
(cons (+ (x-coord point!) (x-coord point2)) 
(+ (y-coord point!) Cy-coord point2)))) 
(def ine Csubtract-points point! point2) 
(cons (- (x-coord point!) (x-coord point2)) 
(- (y-coord point!) (y-coord point2)))) 


function for passing a rectangle to a grephics function 
(def ine (2-point-function the-function the-rectangle) 
(the-function Cleft the-rectangle) 
(top the-rectangle) 
Cright the-rectangle) 
Cbottom the-rectangle))) 


;,this is your basic oval that can draw, erase, invert itself, 
3, tell its dimensions, and receive new dimensions 
(def ine (make-oval . oval-def inition) 
(let (Coval-def inition Capply make-rect oval-def inition))) 
(lambda (message) 
Cif (rectangle? message) 
(set! oval-def inition message) 
(case message 
(DRAW (2-point-function paint-oval oval-def inition)) 
CERASE (2-point-function erase-oval oval-def inition)) 
CINVERT (2-point-function invert-oval oval-def inition)) 
(DESCRIPTION oval-def inition) 
(else (error “make-oval can't handle that definition" 
message ))))))) 


,,8 grow-oval inherits all of the features of an oval, but can 
,,8lso move and change size in more interesting ways 
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(define (make-grow-oval . oval-def ) 
(let CCthis-oval Capply make-oval oval-def))) 
Clambda (the-change . the-amount) 
(let (Cold-description (this-oval ‘description)) 
(real-amount 
Cif the-amount 
Capply make-point the-amount)))) 


(this-oval 
(cese the-change 
(MOVE 
(make-rect 
Cadd-points 
real-amount 
Cleft-top old-description)) 
Cadd-points 
real-amount 
Cright-bottom old-description)))) 
(MOVE-TO 
(make-rect 
real-amount 
Cedd-points 
real-amount 
(subtract-points 
(right-bottom 
old-description) 
Cleft-top 
old-description))))) 
CEXPAND 


(meke-rect 


(subtract-points 
Cleft-top old-description) 
real-amount) 
Cadd-points 
real-amount 
(right-bottom old description)))) 
Celse the-change))))))) 


;;;Mis procedure shows off some ovals 
(def ine Coval-sampler) 


let Coval-i(make-grow-oval 5 5 50 50)) 
Coval-2(make-grow-oval 108 28 130 48)) 
Coval-3C(make-grow-oval 30 98 68 120))) 

(clear-graphics) 

voval-1 'draw) 

Coval-2 ‘draw) 

Coval-3 ‘draw) 

Coval-1 ‘move 5 5) 

Coval-1 ‘erase) 

Coval-2 ‘expand 4 4) 

Coval-2 'invert) 

Coval-3 'move-to 40 60 70 90) 
Coval-3 ‘draw))) 
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Modula-2 Mods 


A Resource Mover in Modula-2 


Modula-2 


Moving Resources In Modula-2 

The Macintosh's built-in ability to deal with resources can 
both complicate and simplify life for the Mac programmer. 
Resources allow many items that would normally be hardcoded 
into a program to be separated from the code and made 
independent of program compilation. Typical resources 
include windows, dialogs, controls, and icons. Many utility- 
type programs need to move resources from one file to 
another. This article will present the steps necessary to move 
resources and provide the sources to a library module and a 
demonstration program. 

Clearing a resource file 

The first routine I needed while designing a module to 
copy resources was a procedure to clear a resource file of all 
resources. In dealing with the Mac, it seems like there's 
always a ToolBox routine at hand to do exactly what you 
want. In this case, I could find no routine to clear a resource 
file. My first cut at writing a resource clearing routine worked 
by finding all the resources that belonged to the desired 
resource file and then individually removing the resources by 
calling RmveResource. For some unexplainable reason, 
this method did not work. Sometimes it would take more 
than one pass over the file to delete all the resources. Out of 
frustration, I resorted to a more brute-force, direct technique. 
This method involved opening the resource file using the File 
Manager and directly manipulating its contents to mimick that 
of an empty, newly created resource file. Figure one shows 
the contents of a resource file after it has been "cleared" by my 
ClearRsrcFile routine (see the commented routine in the 
MoveResources. MOD file). 


PROCEDURE ClearRsrcFile 
(file : ARRAY OF CHAR) : INTEGER; 


There are two ways to open a resource file. Normally, the 
Resource Managers OpenResFile routine is called. This 
routine looks only on the default volume for the specified file 
(unless one passes the volume name as part of the filename; a 
no-no according to Apple and might not work with the HFS). 
Therefore, always do a SetVol to the volume containing the 
resource file before calling OpenResFile. It is interesting 
to note that the Resource Manager in the new ROMS includes 
a call called OpenRFPerm that allows you to specify the 
volume reference number along with the resource file (and 
permission too!) The other way to open a resource file is 
with the File Managers FSOpenRF call. FSOpenRF 
treats the resource file as a traditional data file and 
OpenResFile treats the file as a collection of resources. 
Since the ClearRsrcFile routine needs to go in and fool 
with the resource file directly, I used the FSOpenRF call to 
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Figure 1. A cleared resource file. 
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open the file. 
Copying a resource file 

The next step in designing a resource copying module was 
to design a resource copying routine. I wanted the routine to 
be very simple from a user's point of view. The routine takes 
two resource file reference numbers, one the source and the 
other the destination, and simply copies all resources from one 
file to the other. Other parameters of the routine specify 
whether information about each resource should be printed as 
the resource is copied and whether duplicate resources should 
be replaced or flagged as an error. Finally, a fairly involved 
error record is passed to the resource copying routine so that if 
an error occurs, the caller has a chance at doing some sort of 
sophisticated error recovery. 


PROCEDURE MoveRsrcs 
(src, dest : INTEGER; 
noisy : BOOLEAN; 
allowDuplicate: BOOLEAN; 
VAR error : RsrcErr); 


The resource copying routine (called MoveRsrcs in the 
the MoveResources.MOD file), basically follows these steps: 


1- Turn off resource loading by calling 
SetResLoad(FALSE). This tells the Resource Manager 
not to load the resource data associated with each resource 
into memory (of course, those resources marked as 
" preloadable" will have already been loaded by the 
OpenResFile call). After every Resource Manager call, 
the procedure CheckError is called to check for a 
Resource Manager error. If an error did indeed occur, 
resource loading is turned back on by calling 
SetResLoad(TRUE). Leaving a program without 
setting resource loading back on causes serious problems! 

2- Find all the resources associated with the source resource 
file. We loop through all the resource types and the 
various resources of each type (by calling CountTypes 
and CountResources) and get a handle to each resource. 
Unfortunately, we must look at every resource from every 
open resource file just to find the resources that belong to 
a specific file. When you ask the Resource Manager for a 
resource, it checks all of the open resource files and there 
is no way to limit its search to one file (although the order 
of the search can be changed). The new ROMs, however, 
now implement a number of new Resource Manager calls 
that only search a single resource file (routines such as: 
Count] Resources, GetlIndType, etc). Of course, by using 
any of the new ROM calls, the program wouldn't work on 
a Mac with the old ROMs. The HomeResFile routine 
tells us which resource file a resource belongs to. If the 
resource belongs to the source file we are interested in, 
then the handle to the resource is saved by our module in a 
linked list. 

3- Loop through the selected resources. Each selected resource 
handle is removed from the linked list. 

a- Load the resource into memory by specifically calling 
LoadResource. LoadResource will load the resource 
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even though SetResLoad is FALSE. 

b- Call GetResInfo to find out the resource's name, type, 
and id. 

c- "Detach" the resource with DetachResource. In other 
words, tell the Resource manager to "forget" about it. 

d- Check to see if the destination resource file already contains 
the same resource and handle a possible collision. 

e- Add the resource to the destination resource file. 

4- Turn resource loading back on (SetResLoad(TRUE)) and 
return. 


Step 2 mentioned that the resource manager searches all the 
open resource files when performing various operations. In 
the case of MacModula-2, these files could include: the 
System file, the Modula-2 interpreter, the .LOD file that uses 
the resource copier module, the source resource file (the one 
we're copying), and the destination resource file (the one we're 
copying to). Actually, the Resource Manager keeps a linked 
list of all the open files and it sequentially searches the files in 
the list. By calling UseResFile, one can change the order of 
this linked list. In fact, UseResFile is called in a number of 
places where it is desireable that either the source or 
destination file be searched first. 
An applications program 

The sample application program provides a front-end to the 
MoveResource module (see figure 2). The program (called 
MoveResources.MOD) displays the SFGetFile dialog box 
and prompts the user to select a source resource file. If the file 
has a resource fork, the user is asked to select a destination 
resource file and decide whether the destination resources 
should be cleared. Finally, the resources are copied from the 
Source to the destination file. 

Since the Mac is so tied to resources, it's important that we 
understand how to manipulate these resources. I hope that you 
will be able to make use of the code or concepts discussed in 
this article in your own projects. 


— — ——- MoveResources . DEF 
(* Tom Taylor 
3/07 Poinciana Dr. #137 
Santa Clara, CA 95051 
x) 
DEFINITION MODULE MoveResources; 
(* This module is used for copying 
resources from one file to another. *) 
FROM ResourceManager IMPORT 
ResType; 
EXPORT. QUALIFIED 
RsrcErrType, RsrcErr, 
MoveRsrcs, ClearRsrcFile; 
TYPE 
(* Possible errors during a resource copy *) 
RsrcErrType = (noRsrcError, 
duplicateRsrc, 
otherRsrcError); 
RsrcErr = RECORD 
errType : RsrcErrType; 
CASE RsrcErrType OF 
duplicateRsrc: dupInfo : 
RECORD 
(* The ID and type of 
the offending duplicate 
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FSOpenRF, GetVol, 
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INTEGER; 


: BOOLEAN; 


PROCEDURE MoveRsrcs (src, dest : 


noisy 


: BOOLEAN; 


: RsrcErr ); 


allowDuplicate 
(* Moves all resources from the src resource 


VAR error 


FROM Strings IMPORT 


StrModToMac; 
FROM SYSTEM IMPORT 


file number to the dest resource file number. 
If noisy is true, then information is printed 


If 


allowDuplicate is true, then a destination 


ADR; 
CONST 


resource of the same type and ID as a source 


about each resource as it is copied. 


= -192; 
= g: 


ResNotFound 


NoErr 
FileNotFoundErr = 


resource is repleced by the source resource. 
If allowDuplicate is false, then en error i 
returned when & duplicate is found. *) 
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INTEGER; 


(file: ARRAY OF CHAR) 
(* Clears all resources in the resource file 


PROCEDURE ClearRsrcF ile 


*) 


for maintaining a linked list 


of resource handles. 


IMPORT Handle; 


FROM Storage IMPORT 


ClearRsrcFile returns 


Ø if no error occured or the error number. *) 


specified by 'file'. 


ALLOCATE, DEALLOCATE; 


EXPORT 


END MoveResources. 


———— WoveResources. MOD ———————— 


RmveRsrcNode ; 


AddRsrcNode, 
TYPE 


RsrcPtr = POINTER TO RsrcNode; 
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RsrcNode 


*) 


rsrcHandle : Handle 
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IMPLEMENTATION MODULE MoveResources 
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: RsrcPtr 


next 


END 


J 


(* Pointer to the 
first node. *) 


" 


) 


newNode : RsrcPtr 


to the front of the linked list. *) 
BEGIN 


VAR 
WITH newNode^ DO 


NEWCnewNode); 


rsrcHead : RsrcPtr 
PROCEDURE AddRsrcNode(data : Handle); 


(* This procedure adds a new node 


VAR 


4 


copying resources from one file 
to another. *) 
Write, WriteString, 

Handle, Str255, LongCard; 


(* This module contains the code for 
WriteInt, WriteLn 


FROM MacSystemTypes IMPORT 


IMPORT Storage; 
FROM InOut IMPORT 


:= data; 


rsrcHandle 


FROM ResourceManager IMPORT 


:= rsrcHead; 


next 


END; 


CloseResFile, ResError, 
CountTypes, ResType, 


J 


newNode 


rsrcHead 
END AddRsrcNode 


s 


Select e destination file... 


2 


Handle 


(* This procedure removes a node from 


PROCEDURE RmveRsrcNode() 


It 


returns the resource handle found in 


the front of the linked list. 


vote 


the node or NIL if there are no more 


nodes. *) 


VAR 
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data : Handle; 
oldNode : RsrcPtr; 
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Figure 2. MoveResource program. 
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ELSE 
data := NIL; 
END; 
RETURN data; 
END RmveRsrcNode ; 


BEGIN 
rsrcHead := NIL; (* Init the list header *) 
END LinkedList; 


PROCEDURE MoveRsrcs (src, dest : INTEGER; 
noisy : BOOLEAN; 
allowDuplicate : BOOLEAN; 
VAR error : RsrcErr); 
(* Moves all resources from the src resource 
file number to the dest resource file number. 
If noisy is true, then information is printed 
about each resource as it is copied. If 
allowDuplicete is true, then a destination 
resource of the same type end ID as a source 
resource is replaced by the source resource. 
If allowDuplicate is false, then an error is 
returned when a duplicate is found. *) 


VAR 
theType : ResType; 
rsrcHdl, destHd] : Handle; 
types, rsrcs, theID : INTEGER; 
rsrcName : Str255; 


PROCEDURE CheckError 
(VAR errRec : RsrcErr) : BOOLEAN; 
(* This procedure checks to see if the last 
resource procedure generated an error. If 
So, then the procedure fills in the error 


record. *) 
VAR 
resError : INTEGER; 
BEGIN 
resError := ResError(); (* An error? *) 
IF resError #8 Ø THEN (* Yep... x) 


WITH errRec DO 
errType := otherRsrcError; 
errNum := resError; 
END; 
(* Since we got an error, 
be sure to turn resource 
loading back on so the Mac 
will work as expected. *) 
Se tResLoad( TRUE); 
END; 
RETURN resError * Ø; 
END CheckError; 


BEGIN 
error.errTgpe := noRsrcError; (* Init no error *) 


(* Since we are only interested in figuring 
out which resources exist in the source file, 
we turn off resource loading. This prevents THEN 
the heap from becoming polluted with billions 
of resources. *) 
Se tResLoad(FALSE); 
IF CheckErrorCerror) THEN RETURN END; 


(* Check out all the resource types found in 
all the open resource files (which are 
probably: 

1- System 
2- Modula-2 interpreter 
3- The .LOD file that imports this 
module 
4- The source resource file 
9- The destination resource file) 
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X) 
FOR types := 1 TO CountTypes() DO 
GetIndType( theType, types); (* get the type *) 
(* Go through all the resources of a given 
type. *) 
FOR rsrcs := 1 TO CountResources(theType) DO 
(* Get a handle to the resource. Note 
that the resource isn't loaded because 
we turned resource loading off. *) 
rsrcHdl := GetIndResource( theType,rsrcs); 
IF CheckErrorCerror) THEN RETURN END; 
(* If the resource belongs to the 
source file, then we are interested 
in it. *) 
IF HomeResF ileCrsrcHdl) = src THEN 
(* Save the resource in the linked list *) 
AddRsrcNode(CrsrcHd1 2); 
END; 
END; 
END; 


(* Get a handle to a source resource 
from the linked list. *) 
rsrcHd] := RmveRsrcNode(); 
(* Process until there are no more 
handles in the list... *) 
WHILE rsrcHdl # NIL DO 
IF noisy THEN 
WriteString(' ‘); 
WriteCtheTgpet£1); WriteCtheTypeL 115; 
WriteCtheType[21); WriteCtheType[31); 
WriteStringC' '); 
WriteIntCtheID,2); WriteLn; 
END; 


(* Force the source resource to be loaded *) 
LoadResource(rsrcHd1); 
IF CheckErrorCerror) THEN RETURN END; 


(* Get the resource's vital stats *) 
GetResInfo(rsrcHd1, theID, theType,rsrcName); 
IF CheckErrorCerror) THEN RETURN END; 


(* Make the resource manager forget about 
this resource. *) 

DetachResource(rsrcHd!); 

IF CheckErrorCerror) THEN RETURN END; 


(* Tell the resource manager to search 
the dest resource file before all others *) 
UseResF i leCdest); 


IF CheckErrorCerror) THEN RETURN END; 


(* We've already pulled a resource from the 
Source resource file. Try to grab the same 
one from the destination file. If the grab 
is successful, then we have a duplicate. *) 
destHd] := GetResourceCtheType, theID); 
IF (ResError() = NoErr) AND CHomeResFile(destHd]) =dest) 


IF NOT allowDuplicate THEN 

(* The user requested no duplicates 
So set the error and exit. *) 

WITH error DO 

errlype := duplicateRsrc; 
WITH dupInfo DO 

dupID := theID; 

dupType := theType; 

END; 

(* Before getting out of here, turn 
resource loading back on so the 
Mac will work properly. *) 

Se tResLoad( TRUE); 

RETURN; 
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ELSE 
(* If we got a duplicate and its ok 
with the user, zap the resource 
from the destination resource file 
so it can be replaced with the resource 
from the source file. *) 
RmveResource(destHd1); 
IF CheckErrorCerror) THEN RETURN END; 
END; 
END; 


(* Finally, add the resource from the source 
file to the destination file. The files 
will be updated when they are closed. *) 

AddResource(rsrcHdl , theType, theID,rsrcName); 

IF CheckErrorCerror) THEN RETURN END; 


(* Set things back so the resource manager 
will look at the source resource file 
first. *) 

UseResF i leCsrc); 

IF CheckErrorCerror) THEN RETURN END; 


(* Get another resource hendle from the 
linked list and process it. *) 
rsrcHdl := RmveRsrcNode(); 
END; 


UseResF i leCdest); 
IF CheckErrorCerror) THEN RETURN END; 


(* Turn resource loading back on so 
the Mac won't get mad. *) 
SetResLoadCTRUE); 
IF CheckErrorCerror) THEN RETURN END; 
END MoveRsrcs; 


PROCEDURE ClearRsrcFile 
(file:ARRAY OF CHAR) : INTEGER; 
(* Clears all resources in the resource file 
specified by 'file'. ClearRsrcFile returns 
Q if no error occured or the error number. *) 
CONST 
BufSize = 143; (* Number of words that are 
to be written to the resource 
file. *) 
VAR 
err, vRefNum, refNum : INTEGER; 
filename : Str255; 
rsrcBuffer : ARRAY [1..143] OF INTEGER; 
i : CARDINAL; 
count : LongCard; 
BEGIN 
(* We expect that the file that 
we ere attempting to cleer is 
found on the default volume. *) 
StrModToMac(f ilename,f ile); 
err := GetVolCNIL, vRef Num); 
IF err 8 NoErr THEN RETURN err END; 


(* Open the resource fork. *) 
err := FSOpenRF (filename, vRef Num, ref Num); 
IF err = FileNotFoundErr THEN 
(* If there was no resource file, 
then create one. *) 
CreateResF i leCf ileneme); 
err := ResError(); 
ELSE 
IF err * NoErr THEN RETURN err END; 
(* The resource file already exists. 
Write over the info that's there 
with a resource map that makes the 
resource file look empty. *) 
FOR i := 1 TO BufSize DO 
rsrcBuffer[il := 8; 
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END; 

rsrcBuffer(2] — :- 00100h; 
rsrcBuffer(4] X:- 00100h; 
rsrcBuffer[(8]  := 0001eh; 
rsrcBuffer[130] := 88180h; 
rsrcBuffer[133] := 88109h; 
rsrcBuffer[136] := 980 leh; 
rsrcBuffer[141] := 888 Ich; 
rsrcBuffer[142] := 888 leh; 
rsrcBuffer[143] := -1; 


count.h := Ø; 
count.l := BufSize*2; 
err :- FSWriteCrefNum, count, ADRCrsrcBuf f er 22; 


(* Truncate the resource file to the size 
of an empty resource file. *) 
vRefNum := SetEOFCrefNum, count); 
vRefNum := FSCloseCrefNum); 
END ; 
RETURN err; 
END ClearRsrcFile; 


END MoveResources. 


RercMover . MOD 


(* Tom Taylor 
3787 Poinciana Dr. #137 
Santa Clara, CA 95951 
X) 
MODULE RsrcMover; 
(* This example progrem demonstrates 
a possible use of the MoveResources 
module. It allows the user to move 
resources from one file to another. *) 


IMPORT DialogManager; 


FROM MacInterface IMPORT 
InitViewPort; 


FROM MoveResources IMPORT 
RsrcErrType, RsrcErr, 
MoveRsrcs, CleerRsrcFile; 


FROM DialogManager IMPORT 
GetNewDialog, DialogPtr, 
ModalDialog, DisposDialog; 


FROM MacSystemTypes IMPORT 
LongCard, Str255; 


FROM WindowManager IMPORT 
WindowPtr, ShowWindow, 
GetNewWindow; 


FROM Strings IMPORT 
StrModToMac, StrCat, 
StrMacToMod, StrCpy; 


FROM PackageManager IMPORT 
SFReply, SFTgpel ist, SFGetFile; 


FROM QuickDraw1 IMPORT 
Point, SetPort, 
TextFont; 


FROM FileManager IMPORT 
SetVol; 


FROM ResourceManager IMPORT 
OpenResFile, ResError, 
CloseResF ile; 


FROM SYSTEM IMPORT 
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ADR; 


FROM NumConversions IMPORT 
IntToStr; 


VAR 
behind : LongCard; 


MODULE DialogHandler; 

(* This internal module exports 
procedures that display 
messages in dialog boxes on 
the screen. *) 


IMPORT 
WindowPtr, behind, 
Str255, StrModToMac, 
ShowWindow, IntToStr, 
StrCat, StrCpy; 


FROM DialogManager IMPORT 
GetNewDialog, DialogPtr, 
ParamText, DrawDialog; 

EXPORT 
ShowMessage, 
ShowErrorMessage; 


CONST 
dialogID = 978; (* Resource ID of dialog *) 
VAR 


dPtr : DialogPtr; (* Pointer to the dialog 
box *) 


PROCEDURE ShowMessage(msg : ARRAY OF CHAR); 
(* ShowMessage displays a message in a static 
dialog box *) 
VAR 
S : Str255; 
GIN 


StrModToMac(s, msg); (* Convert to Str255 *) 
ParamText(s,'','',''); (* Stick the msg in the 
dialog box *) 


ShowW indowCdPtr); (* Display the window 
if it's not up *) 
DrawDialog(dPtr); (* Force the dialog 


info to be drawn *) 
END ShowMessage; 


PROCEDURE ShowErrorMessage(msg : ARRAY OF CHAR; 

error : INTEGER); 

(* ShowErrorMessage is the same as ShowMessage 
except that an integer error message number 
is also displayed *) 

VAR 
errMsg : ARRAY [0..100] OF CHAR; 
errNum : ARRAY [0..7] OF CHAR; 
BEGIN 
StrCpyCerrMsg, msg); (* Make a local copy 
of the string *) 

StrCetCerrMsg,' Error = ');(* Append a msg *) 

IntToStrCerror,errNum,8);  (* Convert the num *) 

StrCatCerrMsg, errNum); (* Concet to end of 

the main msg *) 

ShowMessageCerrMsg); (* Display the msg *) 

END ShowErrorMessage; 


BEGIN 
(* Get the basic dialog box from the rsrc file *) 
dPtr :z 
GetNewDialog(dialogID,NIL,WindowPtr(behind2); 
END DielogHandler; 


PROCEDURE SelectRsrcFile(msg : ARRAY OF CHAR; 


R filename : ARRAY OF CHAR; 
ClearTheFile : BOOLEAN): INTEGER; 
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(* Put up the mini-finder and let the user 
select a file. Returns the resource file 
ID or zero if the user wants to cancel. *) 


where : Point; 

reply : SFReply; 

typeList : SFTypeL ist; 

err : INTEGER; 

sPtr : POINTER TO Str255; 

newMsg : ARRAY [0..200] OF CHAR; 


BEGIN 
where.h := 99; 
where.v := 126; 
ShowMessage (msg); 
newMsg := "That file doesn't have a resource fork! E 


StrCatCnewMsg, msg); 
LOOP 


(* Put up mini-finder *) 
SFGetFileCwhere, ' ' ,NIL,-1, typeList,NIL,reply); 
WITH reply DO 
IF NOT good THEN RETURN @ END; (* Hit cancel? *) 
(* OpenResFile doesn't know how to 
deal with volumes very well... *) 
err := SetVolCNIL, vRefNum); 
sPtr := ADR(fName); 
err := OpenResFileCsPtr^); 
(* Save the filename *) 
StrMacToMod(f i lenane, sPtr*^ ); 


(* Ask clear question? *) 
IF Cerr * -1) AND ClearTheFile AND 
EraseQuestionC) THEN 
(* The resource file must be closed 
before we can open and clear it. *) 
CloseResF i leCerr); 
err := CleerRsrcFileCfilename); 
IF err 8# Ø THEN 
ShowErrorMessage( 
"An error occured while clearing the resource file.',err); 


err :s OpenResFileCsPtr^); (* Re-open the file *) 
D: 


a 


IF err * -1 THEN RETURN err END; 

END; 

(* If we make it to here, some error occured. 
Put up a message and bring up the mini- 
finder again *) 

ShowMessage(newMsg); 


END SelectRsrcF ile; 


PROCEDURE EraseQuest ionC ): BOOLEAN; 
CONST 
ereseID = 979; 
IN 


RETURN ShowModalCeraseID) = 1; 
END EraseQuestion; 


PROCEDURE ShowModalCid : INTEGER) : INTEGER; 
(* ShowModal brings up the dialog with id 
= 'id' end returns the number of the 
button pressed. *) 
VAR 


dPtr : DialogPtr; 
item : INTEGER; 
BEGIN 
dPtr := GetNewDialog( id, NIL, WindowPtr(behind)), 
ModalDialog(NIL, item); 
DisposDialog(dPtr); 
RETURN item; 
END ShowModa!; 


CONST 
windID = 913; 
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Chicago = 8 


GoodID = 1023; 
BadID = 1024; 
VAR 
src, dest, err : INTEGER; 
errRec : RsrcErr; 
wind : WindowPtr; 
destFile : ARRAY (90..100] OF CHAR; 
BEGIN 
behind.h := 65535; (* Setup a -1 LongInt *) 
behind.1] := 65535; 


err := Ø; (* Clear the error rememberer *) 
src := SelectRsrcFileC'Select a source file...', 
destFile,FALS 
E); 
IF src * Ø THEN 
dest := 
SelectRsrcFileC'Select a destination file...', 
destF ile, TRUE); 
IF dest * 2 THEN 


TextFont(Chicago); (* ...to make the window title 

come up with the right font *) 

(* Bring up a window to show the resource copy 
information *) 


wind := GetNewWindowCwindID, NIL, 


WindowPtr(behind2); 
SetPort(wind); 
InitViewPort; (* Make Modula-2 aware of the window *) 
(* Now do the work... *) 
MoveRsrcsCsrc, dest, TRUE, FALSE , errRec); 
err := INTEGERCerrRec.errType); (* error occur? *) 
CASE errRec.errType OF 
noRsrcError : 
| duplicateRsrc: 
ShowMessage( 'Duplicate resources error!'); 
| otherRsrcError: 
ShowErrorMessage('An error occured while copying 
resources' ,errRec.errNum); 
END; 
CloseResF ileCsrc?; 
CloseResF ileCdest); 
IF err = Ø THEN 
err := ShowModal(GoodID); 
ELSE 
err := ShowModal(BadID); 
END; 
END; 
END; 
END RsrcMover. 


(* Close up *) 


* Tom Taylor 

* 3767 Poinciana Dr. #137 
* Santa Clara, CA 95051 

x 


* Resource file for RsrcMover 
* demo program. 
x 


MacModula-2:RsrcMover . REL .rsrc 
LODRM2MC 


type DLOG 

,9178 

Null 

31 184 96 489 
Invisible NoGoAway 
1 


My 
978 


Null 

134 102 225 401 
Visible NoGoAway 
1 


ð 
979 


, 1023 

Null 

100 148 168 364 
Visible NoGoAway 
1 


ð 
1023 


, 1024 

Null 

171 92 229 421 
Visible NoGoAway 
1 


ð 
1024 


type DITL 
18 


) 


1 


staticText 

5 5 55 295 

^0 

,979 

3 

BtnItem Enabled 
49 33 81 113 
Yes 


BtnItem Enabled 
49 120 81 200 
No 


StatText Disabled 
6 20 42 277 
Cleer destination resource file before copying resources? 


, 1023 

2 

BtnItem Enabled 
33 54 59 162 
Hoaky Doaky 


StatText Disabled 
10 17 38 200 
Resource copy successful! 


, 1024 
2 


BtnItem Enabled 
24 123 48 206 
Bummer ! 


StatText Disabled 
3 5 25 333 
Sorry, errors occured during the resource copy! 


type WIND 

,913 

Copied Resources 
166 106 316 406 
Visible NoGoAway 
4 


^T — 


e 


(“a “a” re 
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Modula-2 Mods 
Make a Path Name for HFS 


Extending Modula-2 for HFS Support 


The Macintosh low-level File Manager is probably 
familiar to anyone who has programmed in another language 
besides Modula-2 on the Mac. Until the Heirarchical File 
System was released, there wasn't a tremendous amount of 
motivation to use the low level parameter block routines from 
Modula-2. The high-level File Manager routines implemented 
by MacModula-2 were usually enough to get the job done. 
With the release of the Mac Plus, however, the high level 
calls are not enough. Therefore, I decided to implement a 
library module that includes all of the low-level File Manager 
calls specified in the new chapter of the File Manager. 


The Low-Level File Manager 


Most people are already familiar with the low-level File 
Manager. For those who are not, a little introduction would 
be helpful. First of all, the low-level File Manager routines 
exist in ROM. The high level File Manager routines 
described by the File Manager Inside Macintosh chapter do 
not. Instead, the high level calls consist of glue code that 
calls the low-level routines. Each low-level procedure takes 
one parameter: a pointer to a parameter block. This parameter 
block, however, is used to hold many input and output 
parameters. The File Manager chapter does an excellent job of 
showing which fields of the parameter block are used for each 
call. Before using the module presented in this article, you 
must read the File Manager chapter of Inside Macintosh. In 
fact, it would be most helpful if you were to read the new 
chapter that explains the File Manager in terms of both MFS 
and HFS. There are six different types of parameter blocks. 
Three of the six blocks contain variant records. 


A typical low-level File Manager call looks like this: 


PROCEDURE PBCallName 
(paramBlock: PtrToParamBlk; 
async: BOOLEAN) : OsErr; 


The first parameter is a pointer to one of the six different 
parameter blocks. Generally, I find it easiest to declare the 
actual block as a variable and then pass ADR(block) for this 
parameter. The second parameter, "async", specifies whether 
the routine should be executed synchronously or 
asynchronously. It is beyond the scope of this article to 
explain how to use asynchronous calls in an interpreted 
system like MacModula-2. Therefore, my example program 
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Modula-2 


Tom Taylor 
Santa Clara, CA 
MacTutor Contributing Editor 


D) asm logo <>) E System Disk + 
D basic logo 

D BIG LOGO 

D c logo 

D DA icon 

D diskinfo icon 

D dissolve logo 

D exper lisp logo 
D graphics lab icon 


Fig. 1 Standard file Dialog to select file name 


will always perform synchronous calls by passing FALSE for 
this parameter. 


How it all works 


The definition module, PBFileManager.DEF, is very 
straightforward. All of the parameter block types and 
procedures are defined. The implementation module is a bit 
trickier. Basically, every procedure makes a call to the 
procedure LowLevelPB passing four parameters: the parameter 
block address, the asynch flag, the value of the A-Trap that 
ends up calling the actual File Manager procedure, and a 
routine selector for those procedures that are implemented with 
the same A-Trap (which are new, HFS only calls). The 
LowLevelPB procedure immediately makes a call to an 
assembly routine that calls the toolbox. The assembly routine 
(source in PBFileManagerASM.ASM) must unstack the A- 
Trap value and the asynch flag. If the call is to be performed 
asynchronously, the asynch bit in the trap word is set. In 
either case, the A-Trap is installed and executed and the 
returned value is returned back to the Modula-2 calling 
procedure (and returned back up the many levels of procedure 
calls!). This has to be the simplest library module ever 
written, yet one of the most powerful because it gives the 
Modula-2 programmer almost complete control of the Mac's 
file system. That is why I thought it is an appropriate subject 
for this month's article. 


An example program 
Any module is incomplete without an example program. 


The program here, MakePath.MOD, shows how to find the 
complete pathname to a file. The program puts up the 
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| The Path Name on this HFS Volume is: 


Typesetting Tools: Mudula-2 Stuff: Source Code: Modula-2 


Fig. 2 Path Name Program constructs Path 


SFGetFile and allows the user to select any file. Then the 
program displays a window with the file's complete path name 
(up to 255 characters, anyway...). Besides showing how to 
use a few of the low-level File Manager routines, it also 
shows how to determine if the host Mac is running the HFS 
file system and whether a volume is an HFS or MFS volume. 
Because of this, the program will run on any Mac, HFS or not 
(fat or skinny, regular or Plus, etc.). Macintosh Technical 
Note #57 says that the location 03F6h contains a global flag 
that says whether HFS is installed or not. Therefore, the 
variable HFS in MakePath.MOD is declared as: 


VAR 
HFS [03f6h] : INTEGER; 


If HFS = -1, the Macintosh is running MFS, else it's 
running HFS. When HFS is installed, it's also necessary to 
determine whether a volume is a MFS or HFS volume. The 
PBHGetVInfo call will return a field in the parameter block 
called IOVSigWord. This variable will be D2D7h for a MFS 
volume and 4244h for an HFS volume. 


For HFS volumes, the PBGetCatInfo call is the 
basis for building path names. By passing -1 in the 
ioFDirIndex field, PBGetCatInfo will return information about 
the directory with the WDRefNum passed in the ioVRefNum 
field. Every directory on an HFS volume has a different 
directory ID. The root directory always has directory ID of 2. 
Not only does PBGetCatInfo return the directory ID (in 
ioDrDirID) and the directory's name (in ioNamePtr), it also 
returns the directory's parent ID. By calling PBGetCatInfo 
until the directory ID equals two, the path name can be built. 


Here are the steps for building the PBFileManager 
module and the example program: 


-- To make the library module... -— 


1- Assemble PBFileManagerASM.ASM 

2- Link (using MDS or Consulair Link) the 
PBFileManagerASM.REL file using the file 
PBFileManagerASM.link 

3- Run RMaker on PBFileManager.r 

4- Rename PBFileManager.REL.RSRC to PBFileManager.REL 

5- Using M2 Compiler, compile PBFileManager.DEF and 
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PBFileManager. MOD 


— To make the example program... — 


1- Run RMaker on MakePath.r 

2- Rename MakePath.REL.RSRC to MakePath.REL 

3- Using M2 Compiler, compile and link MekePath.MOD 
4- Execute MakePath.LOD and have fun! 


PBF i leManager .DEF 


(* Tom Taylor 
3707 Poinciana Dr. #137 
Santa Clara, CA 95051 *) 


DEFINITION MODULE PBF i leManager ; 


(* This module defines the low level 
file system described in the latest 
File Manager documentation. The 
types and procedures defined in 
this module support both MFS and 
HFS calls. *) 


FROM OSQueues IMPORT 
QElemPtr; 

FROM MacSystemTypes IMPORT 
LongCard, Ptr, OsErr, 
StringPtr; 

FROM FileManager IMPORT 


FInfo; 
FROM SYSTEM IMPORT 
ADDRESS; 


EXPORT QUALIFIED 


(* Types *) 
ParamBlkType, ParmBikPtr, ParamBlockRec, 
CMovePBPtr, CMovePBRec, HParmBlkPtr, 
HPeremBlockRec, WDPBPtr, WDPBRec, 
CInfoType, CInfoPBPtr, CInfoPBRec, 
FCBPBPtr, FCBPBRec, 


(* Procedures *) 
PBMountVol, PBGetVInfo, PBHGetVInfo, 
PBHSetVInfo, PBGetVol, PBHGetVol, 
PBSetVol, PBHSetVol, PBFlushVol, 
PBUnmountVol, PBOffLine, PBEject, 
PBOpen, PBHOpen, PBOpenRF, 
PBHOpenRF, PBLockRange, 
PBUnlockRenge, PBRead, PBWrite, 
PBGetFPos, PBSetFPos, PBGetEOF, 
PBSetEOF, PBAllocate, PBAllocContig, 
PBFlushFile, PBClose, PBCreate, 
PBHCreate, PBDirCreate, PBDelete, 
PBHDelete, PBGetFInfo, PBHGetF Info, 
PBSetFInfo, PBHSetFInfo, PBSetFLock, 
PBHSetFLock, PBRstFLock, PBHRstFLock, 
PBSetFVers, PBRename, PBHRename, 
PBGetCatInfo, PBSetCatInfo, PBCatMove, 
PBOpenWD, PBCloseWD, PBGetWDInfo, 
PBGetFCBInfo; 


TYPE 


ParamBlkType = CioParem, fileParam, 
volumeParam, cntriPaeram); 


ParmBlkPtr = POINTER TO PeramBlockRec; 
ParamBlockRec = RECORD 


qL ink: QElemPtr; 
qType: INTEGER; 
ioTrep: INTEGER; 
ioCmdAddr : Ptr; 
ioCompletion: ADDRESS; 
ioResult: OsErr; 
ioNameP tr : StringPtr; 
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ioVRef Num: 


INTEGER; 


CASE ParamBlkType OF 


ioParam: 
ioRefNum: 
ioVersPerm: 


INTEGER; 
ARRAY [8..1] OF CHAR; 


(* ioVersPerm[0] = ioVersNum 
ioVersPerm[1] = ioPermssn *) 


ioMisc: 

ioBuf fer: 
ioReqCount: 
ioActCount: 
ioPosMode: 
ioPosOffset: 
| fileParam: 
ioFRefNum: 
ioFVersNum: 


Ptr; 

Ptr; 
LongCard; 
LongCard; 
INTEGER; 
LongCard; 


INTEGER; 
ARRAY [9..1] OF CHAR; 


(* joFVersNum(@] = ioFVersNum 
ioFVersNum[1] = filler1 *) 


ioFDirIndex: 


ioFlAttrVers: 


INTEGER; 


ARRAY [@..1] OF CHAR; 


(* ioFlAttrVers[9] = ioFlAttrib 
ioFlAttrVers[1] = ioFlVersNum *) 


ioFlFndr Info: FInfo; 
ioFlNum: LongCard; 
ioF 1StBlk: INTEGER; 
ioF ILgLen: LongCard; 
iof 1PyLen: LongCard; 
ioF IRStBIk : INTEGER; 
ioF IRLgLen: LongCard; 
ioF IRPyLen: LongCard; 
ioF 1CrDat: LongCard; 
ioF 1MdDat: LongCard; 
| volumeParam: 
filler2: LongCard; 
1oVolIndex: INTEGER; 
ioVCrDate: LongCard; 
ioVLSBkUp : LongCard; 
ioVAtrb: INTEGER; 
ioVNmF ls: INTEGER; 
ioVDirSt: INTEGER; 
ioVBILn: INTEGER; 
1oVNmATBIks: INTEGER; 
1oVATBIkS iz: LongCard; 
ioVClpSiz: LongCard; 
joA1BISt: INTEGER; 
ToVNxtFNum : LongCard; 
ioVFrBlk: INTEGER; 
| cntr1Param: 
(* used by Device Manager *) 

END; 

END; 

CMovePBPtr = POINTER TO CMovePBRec; 


CMovePBRec = RECORD 


ql ink: 
qType: 
ioTrap: 
ioCmdAddr : 


ioCompletion: 


ioResult: 
ioNamePtr : 
ioVRef Num: 
filleri: 
ioNewName : 
filler2: 
ioNewDir ID: 
fillers: 
ioDirID: 
END; 


HParmBikPtr = POINTER TO HParamB lockRec; 


QElemPtr; 
INTEGER; 
INTEGER; 
Ptr; 
ADDRESS; 
OsErr; 
StringPtr; 
INTEGER; 
LongCerd; 
StringPtr; 
LongCard; 
LongCard; 


ARRAY [1..2] OF LongCard; 


LongCerd; 


HParamBlockRec = RECORD 


qL ink: 


qType: 
ioTrap: 
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QElemPtr; 
INTEGER; 
INTEGER; 


ioCmdAddr : 
ioCompletion: 
ioResult: 
ioNamePtr : 
ioVRef Num: 


Ptr; 
ADDRESS; 
OsErr; 
StringPtr; 
INTEGER; 


CASE ParamBlkType OF 


ioParam: 
ioRefNum: 
ioVersPerm: 


INTEGER; 


ARRAY [0..1] OF CHAR; 


(* ioVersPerm[90] = ioVersNum 
ioVersPerm[1] = ioPermssn *) 


ioMisc: 

ioBuf fer: 
ToReqCount : 
ioActCount: 
ioPosMode: 
ioPosOffset: 
| fileParam: 
ioFRef Num: 
ioFVersNum: 


Ptr; 

Ptr; 
LongCard; 
LongCard; 
INTEGER; 
LongCard; 


INTEGER; 
ARRAY [@..1] OF CHAR; 


(* ioFVersNum[90] = ioFVersNum 
ioFVersNum[1] = filler] *) 


ioFDirIndex: 
ioFlAttrVers: 


INTEGER; 


ARRAY [0..1J OF CHAR; 


(* ioFlAttrVers[2] = ioFlAttrib 
ioFlAttrVers[1] = ioFlVersNum *) 


ioF IFndr Info: FInfo; 
ioDirID: LongCard; 
ioF IStBTk : INTEGER; 
ioF lLgLen: LongCard; 
ioF 1PyLen: LongCard; 
ioF IRStBlk: INTEGER; 
ioF IRLgLen: LongCard; 
ioF IRPyLen: LongCard; 
ioFlCrDat: LongCard; 
ioF 1MdDat: LongCard; 
| volumeParam: 
filler2: LongCard; 
ioVol Index: INTEGER; 
ioVCrDate: LongCard; 
ioVLsMod: LongCard; 
ioVAtrb: INTEGER; 
ToVNnF 1s: INTEGER; 
1oVBitMap: INTEGER; 
ioAllocPtr: INTEGER; 
1oVNnA1BTks : INTEGER; 
1oVATBIkS iz: LongCard; 
ioVClpSiz: LongCard; 
ioA1B1St: INTEGER; 
ToVNxtCNID: LongCard; 
ToVFrBlk: INTEGER; 
ioVSigWord: INTEGER; 
ioVDrvInfo: INTEGER; 
ToVDRef Num: INTEGER; 
ioVFSID: INTEGER; 
ioVBkUp: LongCard; 
ioVSeqNum: INTEGER; 
ioVWrCnt: LongCard; 
ioVFilCnt: LongCard; 
ioVDirCnt: LongCard; 
ioVFndr Info: 
ARRAY [1..8] OF LongCard; 

END; 

END; 


WDPBPtr - POINTER 


TO WDPBRec; 


WDPBRec 
qLink: 
qType: 
ioTrap: 
ioCmdAdar : 

ioCompletion: 
ioResult: 
ioNamePtr : 


RECORD 


QElemPtr; 
INTEGER; 
INTEGER; 
Ptr; 
ADDRESS; 
OsErr; 
StringPtr; 


505 


ioVRef Num: INTEGER; ioFCBClpSiz: LongCard; 

filler: INTEGER; ioFCBPar ID: LongCard; 

ioWDIndex: INTEGER; END; 

ioWDProcID: LongCard; 

ioWDVRef Num: INTEGER; PROCEDURE PBMountVol 

filler2: ARRAY (1..7] OF INTEGER; (pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
ioWDDir ID: LongCard; PROCEDURE PBGetVInfo 


END; (pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 


PROCEDURE PBHGetVInfo 
CInfoType = ChFileInfo, dirInfo); (pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
CInfoPBPtr = POINTER TO CInfoPBRec; 


PROCEDURE PBHSetVInfo 


CInfoPBRec RECORD (pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
ql ink: QElenPtr; PROCEDURE PBGetVol 
qType: INTEGER; (pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
ioTrep: INTEGER; PROCEDURE PBHGetVol 
ioCmdAddr : Ptr; (pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
ioCompletion: ADDRESS; PROCEDURE PBSetVol 
ioResult: OsErr ; (pB1k: ParmBlkPtr; async: BOOLEAN) : OsErr; 
ioNamePtr : StringPtr; PROCEDURE PBHSetVol 
ioVRef Num: INTEGER; (pBlk: WDPBPtr; async: BOOLEAN) : OsErr; 
ioFRef Nun: INTEGER; PROCEDURE FBFlushVol 
filler: INTEGER; (pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
ioFDirIndex: INTEGER; PROCEDURE PBUnmountVol 

ioFlAttrib: ARRAY (0..1] OF CHAR; (pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 


(* ioFlAttrib[2] = ioFlAttrib 


PROCEDURE PBOffLine 
ioFlAttrib[1] = filler2 *) 


(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 


CASE CInfoType OF 


hFileInfo: 
ioFlFndrInfo: 
ioF lNum: 
ioF 1StBlk: 
iof 1LgLen: 
ioF 1PyLen: 
ioF IRStB1k: 
ioF IRLgLen: 
ioF IRPyLen: 
ioF 1CrDat: 
ioF IMdDat : 
iof 1BkDat: 


ioF 1XFndr Info: 


ioF 1Par ID: 
ioFlClpSiz: 

| dirInfo: 
ioDrUsrWds: 
ioDrDirID: 
ioDrNmF Is: 
filler3: 
ioDrCrDat : 
ioDrMdDet : 
ioDrBkDat: 
ioDrFndr Info: 
ioDrParID: 
END; 

END; 


FInfo; 
LongCard; 
INTEGER; 
LongCard; 
LongCard; 
INTEGER; 
LongCard; 
LongCard; 
LongCard; 
LongCard; 
LongCard; 
FInfo; 
LongCard; 
LongCard; 


ARRAY [1..8] OF INTEGER; 
LongCard; 
INTEGER; 
ARRAY [1..9) OF INTEGER; 
LongCard; 
LongCard; 
LongCard; 
ARRAY [1..8] OF INTEGER; 
LongCard; 


FCBPBPtr = POINTER TO FCBPBRec; 


FCBPBRec = RECORD 


qLink: 
qType: 
ioTrep: 
ioCmdAddr : 
ioCompletion: 
ioResult: 
ioNamePtr : 
ioVRef Num: 
ioRef Num: 
filler: 
ioFCBIndx: 
ioFCBFINm: 
ioFCBF lags: 
ioFCBStBlk: 
ioFCBEOF : 
ioFCBPLen: 
ioFCBCrPs: 
ioFCBVRefNum: 
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QElemPtr ; 
INTEGER; 
INTEGER; 
Ptr; 


INTEGER; 
LongCard; 
LongCard; 
INTEGER; 
INTEGER; 
LongCard; 
LongCard; 
LongCard; 
INTEGER; 


PROCEDURE PBE ject 


(pBlk: ParmBlkPtr; async: 


PROCEDURE PBOpen 
(pBlk: ParmBlkPtr; async: 
PROCEDURE PBHOpen 


(pBlk: HParmBlkPtr; async: 


PROCEDURE PBOpenRF 
(pBlk: ParmBlkPtr; async: 
PROCEDURE PBHOpenRF 


(pBlk: HParmBlkPtr; async: 


PROCEDURE PBLockRange 

(pBlk: PermBlkPtr; async: 
PROCEDURE PBUnlockRange 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBRead 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBWrite 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBGetFPos 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBSetFPos 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBGetEOF 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBSetEOF 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBA1 locate 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBAllocContig 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBF lushF ile 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBClose 

(pBlk: ParmBlkPtr; async: 
PROCEDURE PBCreate 

(pBlk: ParmBikPtr; async: 
PROCEDURE PBHCreate 


BOOLEAN) : 
BOOLEAN) : 
BOOLEAN) 
BOOLEAN) : 
BOOLEAN) 
BOOLEAN) : 
BOOLEAN) : 
BOOLEAN) : 
BOOLEAN) : 
BOOLEAN) : 
BOOLEAN) : 
BOOLEAN) 
BOOLEAN) : 
BOOLEAN) 
BOOLEAN) 
BOOLEAN) : 
BOOLEAN) : 
BOOLEAN) : 


(pBlk: HParmBlkPtr; async: BOOLEAN) 


PROCEDURE PBDirCreate 


(pBlk: HParmBikPtr; async: BOOLEAN) 


PROCEDURE PBDelete 
(pBlk: ParmBlkPtr; async: 
PROCEDURE PBHDelete 


BOOLEAN) 


(pBlk: HParmBlkPtr; async: BOOLEAN) 


PROCEDURE PBGetF Info 


(pBlk: ParmBlkPtr; async: BOOLEAN) : 


PROCEDURE PBHGetFInfo 


(pBlk: HPaermBlkPtr; async: BOOLEAN) 


PROCEDURE PBSetF Info 
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OsErr; 
OsErr; 
: OsErr; 
OsErr; 
: OsErr; 
OsErr; 
OsErr; 
OsErr; 
OsErr ; 
OsErr ; 


OsErr ; 


: OsErr; 


OsErr; 


: OsErr; 


: OsErr; 


OsErr; 
OsErr; 
OsErr; 
: OsErr; 


: OsErr; 


: OsErr; 


: OsErr; 
OsErr; 


: OsErr; 


(pBlk: ParmBlkPtr; async: BOOLEAN) : 
PROCEDURE PBHSetF Info 

(pBlk: HParmBlkPtr; async: BOOLEAN) : 
PROCEDURE PBSetFLock 

(pBlk: ParmBlkPtr; async: BOOLEAN) : 
PROCEDURE PBHSe tFLock 

(pBlk: HParmBlkPtr; async: BOOLEAN) : 
PROCEDURE PBRstFLock 

(pBlk: ParmBikPtr; async: BOOLEAN) 
PROCEDURE PBHRstFLock 

(pBlk: HPermBlkPtr; async: BOOLEAN) 
PROCEDURE PBSetFVers 

(pBlk: ParmBlkPir; async: BOOLEAN) : 
PROCEDURE PBRename 

(pBlk: ParmBlkPtr; async: BOOLEAN) : 
PROCEDURE PBHRename 

(pBlk: HParmBlkPtr; async: BOOLEAN) : 
PROCEDURE PBGetCatInfo 

(pBlk: CInfoPBPtr; async: BOOLEAN) : 
PROCEDURE PBSetCatInfo 

(pBlk: CInfoPBPtr; async: BOOLEAN) : 
PROCEDURE PBCatMove 

(pBlk: CInfoPBPtr; async: BOOLEAN) : 
PROCEDURE PBOpenWD 

(pBlk: WDPBPtr; async: BOOLEAN) : OsE 
PROCEDURE PBCloseWD 

(pBlk: WDPBPtr; async: BOOLEAN) : OSE 
PROCEDURE PBGetWDInfo 

(pBlk: WOPBPtr; async: BOOLEAN) : OSE 
PROCEDURE PBGetFCBInfo 

(pBlk: FCBPBPtr; async: BOOLEAN) : Os 


END PBFileManager . 
—— PBF i leManager .M0D —————— 


(* Tom Taylor 
3787 Poinciana Dr. #137 
Santa Clara, CA 95051 *) 


IMPLEMENTATION MODULE PBF i leManager; 


(* This module implements the low level 
file system described in the latest 
File Manager documentation. The 
procedures implemented in this 
module support both MFS and HFS 
calls. However, attempting to 
call an HFS-only routine on a 
system without HFS will bomb. *) 


FROM ASMInterface IMPORT 
ASM_MCode, InstallAssembly; 

FROM Terminal IMPORT 
WriteString; 

FROM MacSystemTypes IMPORT 
OsErr; 

FROM SYSTEM IMPORT 
ADDRESS; 


VAR 
modnum : INTEGER; (* Module number of 
assembly routine *) 


PROCEDURE PBMountVol 


OsErr; 
OsErr; 
OsErr; 


OsErr; 


: OsErr; 


: OsErr; 


OsErr; 
OsErr; 
OsErr; 
OsErr; 
OsErr; 
OsErr; 
rr; 
rr; 
rr; 


Err; 


(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 


BEGIN 


RETURN LowLevelPB (pBlk, async, GAQOFh, 0); 


END PBMountVol; 
PROCEDURE PBGetVInfo 


(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 


BEGIN 


RETURN LowLevelPB CpBlk, async, 0A007h, 0); 


END PBGetVInfo; 
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PROCEDURE PBHGetVInfo 
(pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 2A297h, Ø); 
END PBHGetVInfo; 


PROCEDURE PBHSetVInfo 
(pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A260h, 11); 
END PBHSetVInfo; 


PROCEDURE PBGetVol 
(pBlk: ParmBlkPtr; async: BOOLEAND : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, OAD 14h, Ø); 
END PBGetVol; 


PROCEDURE PBHGetVo1 
(pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A214h, Ø); 
END PBHGetVol; 


PROCEDURE PBSetVol 
(pBlk: PermBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, QAQ 15h, 0); 
END PBSetVo1; 


PROCEDURE PBHSetVo] 
(pBlk: WDPBPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A215h, 0); 
END PBHSetVo1; 


PROCEDURE PBF lushVol 
(pBlk: ParmBikPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, ?AQ13h, 8); 
END PBFlushVo!; 


PROCEDURE PBUnmountVo1 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, @AQBEh, Ø); 
END PBUnmountVol; 


PROCEDURE PBOffLine 
(pBlk: PermBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A35h, 0); 
END PBOffLine; 


PROCEDURE PBEject 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, BAS17h, Ø); 
END PBEject; 


PROCEDURE PBOpen 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, ØABØØh, 9); 
END PBOpen; 


PROCEDURE PBHOpen 
(pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, @A2@Fh, 9); 
END PBHOpen; 


PROCEDURE PBOpenRF 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
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RETURN LowLevelPB CpBlk, async, SA@@Ah, 9); 
END PBOpenkF ; 


PROCEDURE PBHOpenRF 


(pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 


BEGIN 
RETURN LowLevelPB (pBlk, async, 0A20Ah, 8); 
END PBHOpenRF ; 


PROCEDURE PBLockRange 
(pBlk: PermBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 2A260h, 16); 
END PBLockRange; 


PROCEDURE PBUnlockRenge 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 2A260h, 17); 
END PBUnlockRange; 


PROCEDURE PBRead 
(pBlk: PermBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 2A002h, 0); 
END PBRead; 


PROCEDURE PBWrite 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 9A003h, Ø); 
END PBWrite; 


PROCEDURE PBGetFPos 
C(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 2A218h, Ø); 
END PBGetFPos; 


PROCEDURE PBSetFPos 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 8A044h, Ø); 
END PBSetFPos; 


PROCEDURE PBGetEOF 
(pBlk: PermBlkPtr; async: BOOLEAN) : OstErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 9A011h, Ø); 
END PBGetEOF; 


PROCEDURE PBSetEOF 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 2A212h, Ø); 
END PBSetEOF; 


PROCEDURE PBAllocate 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 9A210h, 8); 
END PBA1 locate; 


PROCEDURE PBAllocContig 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, A210h, Ø); 
END PBAllocContig; 


PROCEDURE PBF lushF ile 
(pBik: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 9A945h, Ø); 
END PBF lushF ile; 
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PROCEDURE PBClose 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 9A00]h, 9); 
END PBClose; 


PROCEDURE PBCreate 


(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 9A008h, 0); 
END PBCreate; 


PROCEDURE PBHCreate 
(pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, £A208h, 0); 
END PBHCreate; 


PROCEDURE PBDirCreate 
(pBlk: HParmBikPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 8A268h, 6); 
END PBDirCreate; 


PROCEDURE PBDelete 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 9A009h, 0); 
END PBDelete; 


PROCEDURE PBHDelete 
(pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 0A200h, Ø); 
END PBHDelete; 


PROCEDURE PBGetF Info 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, BA@@Ch, Ø); 
END PBGetF Info; 


PROCEDURE PBHGetF Info 


(pBlk: HPermBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 


RETURN LowLevelPB (pBlk, async, @A20Ch, Ø); 
END PBHGetF Info; 


PROCEDURE PBSetF Info 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, ØAØØDh, Ø); 
END PBSetF Info; 


PROCEDURE PBHSetFInfo 
(pBlk: HParmBikPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A200h, 8); 
END PBHSetF Info; 


PROCEDURE PBSetFLock 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 0A041h, 0); 
END PBSetFLock; 


PROCEDURE PBHSetFLock 
(pBlk: HParmBikPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB CpBlk, async, 0A241h, Ø); 
END PBHSetFLock; 


PROCEDURE PBRstFLock 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr; 


BEGIN 
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RETURN LowLevelPB CpBlk, async, A042h, 0); 
END PBRstFLock; 


PROCEDURE PBHRstFLock 
(pBlk: HParmBlkPtr; async: BOOLEAN) : OstErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A242h, 9); 
END PBHRstFLock ; 


PROCEDURE PBSetFVers 
(pBlk: ParmBikPtr; async: BOOLEAN) : OstErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, BAB43h, 0); 
END PBSetFVers; 


PROCEDURE PBRename 
(pBlk: ParmBlkPtr; async: BOOLEAN) : OsErr ; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 9A00Bh, 9); 
END PBRename; 


PROCEDURE PBHRename 
(pBlk: HParmBlkPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, ØA2ØBh, Ø); 
END PBHRename; 


PROCEDURE PBGetCatInfo 
(pBlk: CInfoPBPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A260h, 9); 
END PBGetCatInfo; 


PROCEDURE PBSetCatInfo 
(pBlk: CInfoPBPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A260h, 10); 
END PBSetCat Info; 


PROCEDURE PBCatMove 
(pBlk: CInfoPBPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A260h, 5); 
END PBCatMove; 


PROCEDURE PBOpenWD 
(pBlk: WDPBPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A260h, 1); 
END PBOpenWD; 


PROCEDURE PBCloseWD 
(pBlk: WOPBPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pB1k, async, 8A260h, 2); 
END PBCloseWD; 


PROCEDURE PBGetWDInfo 
(pBlk: WDPBPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, 0A260h, 7); 
END PBGetWDInfo; 


PROCEDURE PBGetFCBInfo 
(pBlk: FCBPBPtr; async: BOOLEAN) : OsErr; 
BEGIN 
RETURN LowLevelPB (pBlk, async, @A268h, 8); 
END PBGetFCBInfo; 


PROCEDURE LowLevelPB (pBlk: ADDRESS; 
async: BOOLEAN; 
trap: CARDINAL; 
selector: INTEGER) : OsErr; 
(* This procedure is responsible for calling 
the assembly language routine that actually 
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calls the PB trap. *) 
PROCEDURE LowLevelPB C(pBlk: ADDRESS; 
async: BOOLEAN; 
trap: CARDINAL; 
selector: INTEGER; 
modnum: INTEGER) : OsErr; 
CODE ASM.MCode; Ø; END LowLevelPB; 
EGIN 


RETURN LowLevelPB CpBlk, async, trap, selector, modnum); 
END LowLeveTPB; 


BEGIN 
(* Look for a MASM resource with ID 
of 1986 in current open resource 
files. It better be in our 
.LOD file, put there by M2 Linker *) 
modnum := InstallAssemblyC"", 1986); 
IF modnum « 1 THEN 
WriteStringC"Cannot load PB asm code"); 
HALT 


END; 
END PBFileManager. 
n cESIEN. AC ————————————RERERPQ 
PBF { leManager ASH . AS ————— 


Tom Taylor 
3707 Poinciana Dr. #137 
Santa Clara, CA 95051 


The one procedure in this 

file is used to implement 

all of the PB calls. The 
higher level Module-2 program 
(PBF i leManager . MOD) 

pesses in the actual value 

of the PB trap and the 
procedure here modifies itself 
to execute that. trep. 


Wwe We We We We We Ve We We Ve We Veo BD 


DC.W LowLeve1PB ; Offset to routine 
esyncTrpBitEQU $400 
PROCEDURE LowLevelPB CpBlk: ParmBlkPtr; 


4 

, async: BOOLEAN; 

; trap: CARDINAL; 

; selector: INTEGER) : OsErr; 
LowLeve1PB: 


MOVE.W (A42*,00 


MOVE.W (A4)+,D1 
TST.W CA4 )+ 


; get trap selector 
; CHFS only) 
; get trap value 
; Check for async call 


BEQ.S No tAsync ; nope 

ORI .W MesyncTrpBit,D1  ; yep, make trap async 
NotAsync: 

LEA Trapper , Ad ; get address of trap 

; location 

MOVE.W D1, CAQ) ; install trap 

MOVE.L (A42*,A0 » get param block address 
Trapper : 

DC.W ø ; PB Trap goes here 

MOVE.W DØ,-CA4) ; return result 

RTS 


eee 
PBF 1 leManager ASM .L INK—— ——— 


PBF i leManager ASM 
/Output MacModula-2 : PBF i leManager . made 
j| '9???' '??0^" 


PBF { leManager .r—————- 


* Tom Taylor 
* 3707 Poinciana Dr. #137 
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* Santa Clara, CA 9505] 

* After running this file through 

* RMaker, rename PBF i leManager .REL .RSRC 
* to PBFileManager .REL before compiling 
* PBFileManager.MOD 

MacModu 18-2 : PBF i leManager . REL .RSRC 
LODRM2MC 


Type MASM = PROC 
, 1986 
MacModu1a-2: PBF i leManager . made 


MakePath.M0D— —— — 


(* Tom Taylor 
3787 Poinciana Dr. #137 
Santa Clara, CA 95051 *) 


MODULE MakePath; 


(* This program demonstrates a use of 
the PBFileManager module. 
The program puts up the SFGetFile 
dialog and allows the user to select 
a file. The program will then print 
out the full path name to the file. 
Click the mouse to continue and 
click the SFGetFile's cancel button 
to quit. *) 


FROM PBFileManager IMPORT 
PBGetCatInfo, CInfoPBRec, 
HParamBlockRec, PBHGetVInfo; 

FROM PackageManager IMPORT 
SFGetFile, SFReply, SFTypelL ist; 

FROM SYSTEM IMPORT 
ADR; 

FROM MacSystemTypes IMPORT 
$tr255, LongCard; 

FROM Strings IMPORT 
StrMacCat, StrModToMac; 

FROM WindowManager IMPORT 
WindowPtr, GetNewWindow, 
DisposeW indow; 

FROM QuickDraw! IMPORT 
MoveTo, DrawString, 
SetPort, Point, TextFont; 

FROM DialogManager IMPORT 
StopAlert; 

FROM EventManager IMPORT 
StillDown, Button; 


CONST 
MFSInstalled = -1; (* Location in low 
memory tells whether 
HFS system installed *) 
HFSvolume = 04244h; (* Value specifying a 
HFS volume *) 


TYPE 
Str255Ptr = POINTER TO Str255; 


VAR 
reply : SFReply; 
typelist : SFTypelL ist; 
HFS (ü3f6h] : INTEGER; 


wind : WindowPtr; 
behind : LongCerd; 
path : $tr255; 
where : Point; 

hf sF lag : BOOLEAN; 


PROCEDURE WriteString (s : ARRAY OF CHAR); 
(* This routine simply writes a Modula-2 
style string. *) 
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VAR 
macs : Str255; 


BEGIN 


StrModToMac (macs,s); 
DrawString (macs); 


END WriteString; 
PROCEDURE MakePath (name : Str255Ptr; 


vRefNum : INTEGER; 
VAR path : Str255; 
VAR hfsFlag : BOOLEAN); 


(* This procedure, the focus of this 


program, takes a vRefNum (which might 
be a WORefNum) and figures out the full 
path to the directory. It does this 
by finding the parent each directory 
until the parent is the root. This 
procedure works on both MFS and HFS 


Macs. *) 

VAR 
blk : CInfoPBRec; 
volBlk : HParemBlockRec; 
geiname, volname : Str255; 
Ten : CARDINAL; 


PROCEDURE CheckError Cerr : INTEGER); 
BEGIN 
IF err # Ø THEN 
err := StopAlert (1986, NIL); 


HALT 
END; 
END CheckError; 
BEGIN 

path := name*; (* Start the path with 
the destination file *) 

volname := ""; (* Clear out the volume 
name *) 


(* Get the volume info for the desired 
volume. This calls works on both 
HFS and MFS systems. *) 

WITH volBlk DO 
ioCompletion := NIL; 


ioNemePtr := ADRCvolname?; 

ioVRef Num := vRefNum; 

ioVolIndex := 8; 

ioVSigWord := Ø; 

CheckError CPBHGetVInfo CADRCvolBIk2, FALSE); 
END; 


(* This next line determines whether the HFS 
system is instelled and whether the current 
volume is an HFS volume. *) 

hfsFlag := (HFS * MFSInstalled) AND 

(volBlk.ioVSigWord = HFSvolume); 


IF hfsFleg THEN 
(* Only attempt to build a path name 
deeper than just a volume and file 
on HFS volumes *) 


WITH bik DO 
ioCompletion := NIL; 
ge tname nN 
joNameP tr := ADRCgetname ); 
ioVRefNum ‘= vRefNum; (* Probably a WDRefNum *) 
ioFDirIndex :=-1; (* directory info only *) 


ioDrDirID.r 0.0; (* kludge for LongCerd zero *) 
CheckError (PBGetCatInfo CADRCbIkO, FALSE2); 
WHILE CioDrDirID.h * 2) OR 
CioDrDirID.1 * 2) DO 
(* Keep looping until the directory ID 
is the root directory (dir ID = 2) *) 


(* Insert a colon in the path *) 
len := CARDINALCgetnamet21); 
IF len « 255 THEN 
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INCClen); 


getnaeme[len] := ':'; 
getname[Ø] := CHARClen); 
ND; 


Pd 

(* Append the path made so 
far with the piece we 
just got. *) 

StrMacCat(getname, path); 

(* Save the partial path 
in path. *) 

path := getname; 

getname := ""; 

ioFDirIndex : 


-l; (* directory info only *) 
ioDrParID; (* Get info about 
the parent 
directory. *) 
CheckError CPBGetCatInfo CADR(b1k), FALSE)); 
END; 
END; 

END; 

(* Lastly, append the path to the volume name *) 

len := CARDINALCvolname (81); 

INCClen); 

volname(len] := ':'; 

volname[0] := CHARClen); 

StrMacCat(volname, path); 

path :* volname; 
END MakePath; 


ioDrDirID 


BEGIN 
behind.h := 65535; (* kludge for LongCard -1 *) 
behind. := behind.h; 


where.h := 100; (* location of SFGetFile *) 
where.v :- 100; 
LOOP 


SFGetFile (where, "", NIL, -1, typelist, NIL, reply); 
WITH reply DO 
IF NOT good THEN EXIT END; (* Exit if user hit cancel *) 


(* Figure out path to the file *) 
MakePath CADR(fName), vRefNum, path, hfsF lag); 


TextFont (8); (* so window title comes up right *) 
wind := GetNewWindow (1986, NIL, WindowPtr(behind)); 
SetPort (wind); 
MoveTo (5, 17); 
WriteString ("The path name on this "); 
IF hfsFlag THEN 
WriteString C"HFS"); 
ELSE 
WriteString ("MFS"); 
ND; 


Nr iteString (" volume is:"); 


MoveTo (5, 37); 
DrawString (path); 
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WHILE StillDown C) DO END; 

WHILE NOT Button C) DO END; 

(* Really need to use GetNextEvent 
So this button press is eaten *) 

DisposeWindow (wind); 


4 


END; 
END MakePath. 
a ———— 
---——---- MakcPath.r---—----- 


* Tom Taylor 

* 3707 Poinciana Dr. #137 

* Santa Clara, CA 95051 

* After running this file through 

* RMaker, rename MakePath.REL.RSRC 
* to MakePath.REL before compiling 

* MakePath.MOD 
MacModula-2:MakePath.REL.RSRC 
LODRM2MC 


type ALRT 
1986 

50 50 250 250 
1986 

7tif 


type DITL 
,1986 
2 


button 
100 10 130 80 
OK? 


staticText 
30 80 190 190 
A file manager error occured! 


type WIND 
,1986 

Path Name 
50 3 100 509 
Visible NoGoAway = 
4 


0 TEN 
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Mousehole Report 


Happy New Year! 


This should be an exciting year for MacProducts. The 
MacPlus should be available any day now with 1-meg of 
RAM, 800k drives and a SCSI (say: Scuzzy) interface on the 
back. MacWorkStation is on its way and hopefully "Jonathan" 
will be announced. (Jonathan is supposedly a 3-piece Mac, 
with seperate Keyboard, CPU and Monitor. Rumor has it that 
there will be an optional 17-inch monitor for it!) [Rusty, I 
heard the Jonathan won't appear till 1987. And the MacPlus 
upgrade requires a new case back because the serial ports have 
been changed to round type connectors to make room for the 
SCSI interface, a logic board swap because of the new 
arrangement of daughter boards for up to 4 meg, new ROMS 
and maybe 800K drives? Could be expensive! -Ed.] 


If you are interested in getting on MouseHole, please 
send a SASE to us (see address on column masthead). There 
is usually a 30 day backlog of getting new people on the 
System so be patient. 


Don't have a modem but have some great information? 
Send us a post card telling us about it. If we print it you'll 
get a free MouseHole T-shirt! 


Finder 5.0-HFS 
The Bitman 


The new finder is very nice, some hidden functions are 
even included.. Using the new 5.0 version, with the New 
system, that contains HFS 1.0, or the HARDDRIVE 20 
driver, you should be able to use the heirarcheal structure on 
your harddrive and your floppy without the new roms, the new 
roms will just make your floppies bootable. With the new 
finder, select erase disk, hold down your option key, and click 
initalize, keep the option key held down until the disk is 
complete, now that floppy has HFS installed, you can verify 
this by noticing in the upper left, below the close box, a 
black dot to the very left.. The disk will not boot, but it will 
contain the HFS structure on it, also, there is a way to make 
an existing disk contain HFS, but I forgot how... something 
again to do with option key. Developer should be able to get 
the new roms, can't really say anything now. 


Initializing a Floppy for HFS 
DON L 


To init a floppy you need the file HARD DISK 20 on 
your boot disk. You'll get a message something like HARD 
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DISK STARTUP below the WELCOME TO MACINTOSH 
message if you do. Then keep the option key down until 
initialization is complete. Now is there really a way to 
convert a MFS disk to an HFS disk without reformatting? It 
would sure make life easier if there is. 


Ant Killer 


Hi there, well here's something I didn't know till last 
night. The new System/Finder, 5.0, (at least the copy I got) 
wont initialize a disk unless you've gota 512k! I tried with 
my 128k with the option key & without it, but it just 
wouldn't work, I'd always get a initialization failed(or 
something like that) and it would spit the disk out. 


Mike Steiner 


When you open a locked document from the HFS 
desktop, it tells you that the document is locked and you won't 
be able to save any changes. If the document is a BASIC 
program, (MS BASIC) you will be able to save, regardless of 
the message. When using the files$ (1) function with HFS, 
the string returned is the name of the disk and file. All 
intermediate folders are not identified. That means that if the 
file is in a folder, you will not be able to identify it because 
the filename returned by files$(1) is diskname:filename and 
BASIC will not find the file. Likewise, when saving a file 
using file$(0) to specify the filename, it will be saved in the 
disk window regardless of the folders you specify. Also, 
when opening a file whose name is written into the program, 
such as OPEN FILENAME$ FOR INPUT AS #1 if the file 
is not in the same heirarchy as BASIC (not the BASIC 
program), BASIC will not find it. 


Slow DA's on HD-20 
Jim Reekes 


Has anyone else notice how slow the DA's run on the 
Apple HD20? Open the Scrapbook, then click on the gray 
area of the scroll bar. Wait... Wait.... and then wait for it to 
respond and update the window. This is also the case with 
the Note Pad, and any other DA. On the Note Pad, open note 
page #1, then click on the folded corner, wait....wait....and 
then wait Finally it'll page and update that window. This is 
on a HD20 with about 3megs of software and about ten DA's 
installed. And what's this problem about protected software 
using the attribute file bits? I hear that HFS uses them for 
different reasons now. This makes software protection 
Schemes using this, un-usable on the HD20! Another 
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problem I've found with file utilities on the HD20. Don't use 
‘em. Most of them don't recognize the HD20 formate anyway. 
But if it does, don't trust it. MacZap just "ZAPed" the 
HD20 into bit-heaven. It then became unusable! Thanks to a 
"hidden" utility found in the HD20 test program. Open the 
tester, type "cntrl-D". WOW!!! Now set the "distructive test" 
button to on. Proceed to test the drive. Sometimes you'll 
have to switch the drive and the Mac on and off again, but 
this recovered the HD20 to an "unreadable" state so that I 
could at least formate it and start over. Whew... 
KATZ 
I just recieved my HD 20 today and I am finding a lot of 
software that needs to be changed to work correctly. Another 
problem if you are not using the HD 20 , Finder 4.1 will not 
recognize the external drive. And Apple recommends not using 
Finder 5.0 on floppies so whats the solution? Also none of 
the disk copy utilities will work correctly from HD 20. 
Hacking into the HD-20 
JIM REEKES 
Just got a few new "hacking" tools for the HD20. FEdit 
321 (can view the HD20); F/DA Mover 2.5 Backup DA (a 
DA that will backup the HD20?); HD Diag (diagnostic 
program used in dev. by Nisha and Rodime, this puppie can 
read/write any bit on the HD20. A note about the HD Diag 
says "Do not use Init Mac Dir or the Init Spare Table unless 
youve had a personal discussion with R. Mohme). Also, 
what's the story behind RENE?" That's the name of the device 
driver for the HD20. I heard something about this girl who 
liked to party with software engineers. Can anyone fill us in 
on this? 
Monster Mac & HD 20 
MACOWACO 
Yes, Levco Monsters DO work with Apples HD20. It 
seems the earlier versions of the software had problems. The 
released stuff works fine. Levco tells me their hard disk 
product IS ready to go. They are only awaiting licensing of 
the software from Apple. Apple won't release the software till 
after their product hits the streets. They tell me that their 
disk interface will be the fastest route, but the user only 
notices the speed if there is constant access to the disk. Don't 
forget you got to have a monster to use their interface. With 
all the RAM the disk rarely spins for resources. Why buy their 
product? I asked. They say it will be much cheaper to go with 
it and the low cost PC hard disks out there than with Apple's. 
I also hear rumors about an internal 20 meg HD from Levco. 
Hyper Surprize 
RUSTY HODGE 
General Computer is planning on introducing something 
"really fantastic" at the San Fransisco Mac Expo. This might 
be the rumored clip-on RAM upgrade. 
Multi-mac 
THE ATOM 
Been playing around with this progam a while and 
discovered a few more nice features.... Lazy menus-> sets it 
up like GEM/Amiga. The menu pops up when the mouse is 
in the menu bar, then you point to the menu item and click to 
select it. Downloaded a few things from the Mousehole 
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Download, and with Versaterm, Macpaint, and Finder 
installed, I could start a download, go to the finder, and see 
the file appear on the desktop and watch the free space(at the 
top of the window) go down as the file was downloaded. 
NICE! Also booted up Paint while it was downloading a file 
in the background and tried to draw some stuff. Slowed paint 
down quite a bit, but of course I had Versaterm set at 100% 
priority Good program. 

(MultiMac will not work on the Tecmar MacDrive or the 
Apple HD-20, Hyperdrive and possibly all the other hard 
disks...) 

800K DRIVES 
MACGEORGE 

Got my hands on. a Taiwan Mac 800K drive over the 
weekend. Boots to a 800k formatted floppy in the external. 
Reads 400k Mac disks CopyII Mac functioned on Pinball, 
MacPaint took 9 alligators as to 15 on the Apple 3.5". 
System software was standard 4.1 updates. List price is 
suppose to be $399 ( Apple's is gonna be $695 ) I couldn't 
find a manufacturer name on the disk assembly, but all the 
ICs were Toshiba. This was the first shipment, so I had to 
return the drive today, but using an 800k drive was nice. Any 
Mac built after March '85 should be compatable with it ( 
that's when they changed the ROM's). MacG. 


(It is also possible to hook up a Unidisk 3.5 to a Mac 
with Rev. B. ROMS, all you need is a standard Mac drive 
cable and attach it to the drive in the Unidisk, bypassing the 
Unidisk controller board inside the Unidisk case. Apple has 
been shipping Unidisk 3.5 "service" drives on Mac internal 
drive mounting brackets since November! - Rusty) 

Developer's Converence 
Micro Ghoul 

How many of you are planning on going to the Jan. 14- 
I5th developer's conference up at the Fairmont Hotel in San 
Francisco? Maybe we can set something up. [Why don't they 
tell us about these things? I'm a developer and heard nothing 
about it! -Ed.] 

Multi-Tasking Not For Mac 
Bob Denny 

The Mac as it is now will never be acceptable as a multi- 
tasker for lots of reasons. Strong statement? When I see a 
banker or documentation person at an aerospace outfit using a 
Mac and trusting it while multi-tasking, I'll eat my ... (use 
your imagination). Far more crude machines than the Mac are 
being used by just such folks in just that way, why not Mac? 
The reason is .. memory management .. experienced 


programmers (not wearing suits and ties!) ... sigh! 
New C Book 
DON 
Just picked up a copy of "Using the Macintosh Toolbox with 


C" by Jim Takatsuka, published by Sybex at Crown books for 
$22.95. Apparently the authors are members of Berkley's 


MUG and quite familar the Mac hacking community. 
In their suggested reading section, the only mag 

they mention is MacTutor. Designed for C people 
unfamilar with the toolbox. Looks pretty good. 
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Mousehole Report 


In Anticipation 

As of this writing, we at The MouseHole are anxiously 
waiting to hear about the new Macs that are about to be 
announced. But since you will have undoubtedly heard 
yourself by the time you get this issue, it makes all last 
minute speculation seem in vain. Oh, well, thats life. 

Next month, we'll let you hear about all the exciting 
things that happened at MacExpo in San Fransisco: it should 
be great. But for this month, the exciting happenings still 
seem to be Finder 5.0 and 5.1, the HD-20 and Multi-Mac. 
(Multi-Mac is an exciting new program that gives your Mac 
true multi-tasking abilities. And we thought Switcher was as 
good as it could get!) So, without further ado... - Rusty 

In offence of Microsoft 
MACOWACO 

Well after almost two years and LOTS of angry letters 
they finally sent me my update to Multiplan. The finder on 
the disk was 1.0! 

Mactutor clarification 
BRETT 

The information that was printed in the December 
MacTutor from one of my posts about the configuration of the 
"future" mac, refers to the unit planned for third quarter 86 and 
not the "Mac +". The Mac + is an interum upgrade before the 
“new - improved” Mac shows up. For those interested; Apple 
has confirmed UNIX will be available on a Mac. (Note: it 
Says -a- mac), Silicon manufactures have confirmed Apple has 
many VLSI projects under way - one being a rumored graphics 
controller (that will directly interface with quick draw routines, 
i.e. bit planes). 

So far I haven't been wrong, but it gets harder day by day 
to get information out of Apple. Maybe they mean it when 
they said they would keep quiet about future products. 

Multi-Mac 
DON 

Some Multi-Mac experiences and notes: As MacoWaco 
said, MM won't run on any volume except the boot volume. 
Even if the new volume has the System and Finder on it. 
Never, never, never try to rum MM twice. The Mac locks up 
solid. Never try printing inside a program that resides on 
another disk with a system file. Not only will you bomb out 
to the flaming pits of perdition the moment you activate 
another program (especially communications software), BUT 
you can completely screw up the disk that program is on. I did 
this once with my MS-Word disk. MM fornicated the Word 
disk so thoroughly, I couldn't get the drives to even recognize 
it as Macintosh disk. It is best never to insert another disk 
into either drive that has either a System, Finder, ImageWriter 
or LaserWriter file on it while you are running MM. Only run 
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programs on non-System disks. Never try to run MM on a 
HyperDrive ... unless of course you enjoy using Backup to 
restore most of your Hyper to its original state. Never run the 
PRAM utility under MM. It will not only bomb the Mac.it 
can screw up your parameter RAM. This IS easily fixed, but 
that doesn't mean it isn't annoying. Never use Donald Brown's 
MockWrite under MM, unless you close it between 
applications. It bombs  effortlessly. Don' use the 
continuation DA under MM. Not only is it unnecessary, but it 
will really confuse the Sheol out of the Mac trying to execute 
two programs that shouldn't work anyway. 

All in all, Multi-Mac is an amazing program. Maybe 
whats-his-name will get it to run on a hard disk one of these 
days. DEVIN B. KING 

I have recently been able to run MultiMac 2.8 on my 
MacBottom 20 with the 2.01 software. Also, I have noticed 
that MM will not run with some modified systems (i.e. 
FKEY installations). 

Speed up Finder 4.1 
ANT KILLER 

(Well, a little!) Open Finder with the Open File 
command in FEdit, then find these hex strings and change to 
4E71's (NOP's). If they're not at these exact locations, just do 
a hex search for the strings. 


Sector: 13 Pos: 220 

Look for: 486E FFEO A8A1 

Change to: 4E71 4E71 4E71 

Sector: 13 Pos: 308 

Look for: 486E FFF8 A8A1 486E FFEO A8A1 

Change to: 4E71 4E71 4E71 4E71 4E71 4E71 

Sector: 13 Pos: 380 

Look for: 486E FFEO A8A1 486E FFE8 A8A1 486E 
FFEO A8A1 

Change to: 4E71 4E71 4E71 4E71 4E71 4E71 4E71 
4E71 4E71 


This stops the FrameRects (Zooming effect) from 
happening when you open or close a window from the 
Desktop, kinda weird, why do this? I don't know! [Makes it 
look like it's opening up, silly! (Probably left over from Jeff 
Raskin's original notebook Mac concept.) -Ed ] 

Hard Disk Notes 
GARY VOTH 

Apple has in beta-test a large (36k) DA for the HD 20 
called Backup. It is not available yet, however, and probably 
won't be before the 1st quarter of' 86. Like HFS itself, it is 
probably meant to be an "insanely-great" implementation of 
what is usually a straight-forward utility. Because it takes 
üme to develop optimum Mac software, we will probably 
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have to live without it for a while longer. Expect it to 
support all HFS-compatible hard disks and the 800K drives as 
a backup medium. [THANK YOU APPLE!! -Ed.] 

I am still using Finder 5.0 (supplied with the HD 20). I 
have about 7M loaded onto the disk now and am not 
experiencing the slow Scrapbook phenomenon. The 
Scrapbook works just fine, much faster than with floppies. 
What advantages are there to Finder 5.1? [Bug fixes... -Ed.] 

Random notes: Copy II Mac Hard Disk 4.2 will install 
Jazz onto the HD with no apparent problems. However, do 
not try it with anything else! All copy protection schemes 
which use the invisible/locked/protected file method, ordinarily 
the easiest to circumvent, will cause a system error. Copy II 
does not yet handle the new Finder flags properly. 

You can also install Excel by making a copy of the 
program disk with Copy II Mac 4.3, then running the 
Microsoft hard disk install utility off of the copy disk. 
NEVER install from the master disk itself, as Microsoft 
allows only one installation, period. You cannot "un-install" 
your copy of Excel to move it from one hard disk to another! 

The latest version of ResEdit and FEdit can each handle 
the HD 20 in a limited way. ResEdit seems to work well, but 
FEdit is safe to use only in peek mode. ResEdit allows the 
setting of most Finder flag bits except the protect bit. That 
means that, for now, I haven't been able to run a copy of Word 
on the hard disk without the Word master. It is a simple 
matter to unprotect Word (or Multiplan, File and Chart), even 
if you can't directly copy the key file from the floppy to the 
hard disk. Simply use ResEdit to make a new blank resource 
fork, name it "Kensh Rutha" (or whatever name Microsoft 
uses), then make it invisible, locked, and protected. Voila! 
The only catch is, we don't have a utility for HFS to set the 
protect bit yet! [Why? Sounds suspicous...-Ed.] 

By the way, most of you that read the trade papers are 
probably aware of the hoopla surrounding the hidden messages 
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planted in Microsofts MS-DOS applications. People have 
discovered worms that supposedly destroy "illegal" copies and 
browbeat the user with threats. Well, one of the hidden files 
on the Excel master disk is called "Tsunami," after the giant 
tidal wave... More Hard Disk Comments 
BRETT 
With all this talk about the HD20, I just had to make a 
quick comment about my Hyper. I am (shock.  gasp..) 
content! I love my 10 meg Hyper/512K RAM Mac. With 
the Aztec development software and a few other common 
(macpaint, macwrite, ...) programs always loaded, it does all I 
need. If I don't want to see it I just boot off a floppy. I don't 
need problems with new drives, new operating systems, new 
bugs... Bliss, for once with a computer I have true bliss! 
MouseHole Mailbox: Draw Complaints 
Remedied 
Alan Lee 
In response to More Draw 1.9 Complaints, Bob Denny 
(Mac Tutor, Dec ^85) and Draw Bugs, MacoWaco (Mac Tutor, 
Oct ^85)..This "bug" only seems to occur when "custom 
rulers are in use. To see the the remedy (in Draw 1.7,at least): 
Create a box, type some text while the box is selected, 
creating a centered text in the box. Group it. Select Turn 
Grid Off from the Layout menu. Then grab the grouped 
"object" with the arrow and drag it around in circles, 5 or 6 
times. (Watch what happens to your text!) Draw tries to align 
the box and the text to the grid treating them as independent 
objects when the Grid is Turned On. 
Free Upgrade! 
HIGH ORDER BYTE 
The Wall Street Journal reported today that Apple is 
offering a free upgrade to all its Mac owners. Just come in to 
any Apple dealer, and free of charge, they will grind Steve 
Jobs name off the inside back cover of your Macintosh. (Hee 
hee!) 
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It has been another exciting month at the MouseHole, 
but then again, aren't they all? This month was exciting 
because of the San Fransisco Mac Expo, which I wasn't able 
to attend due to a previous engagement. Even without me, the 
"MouseHole Pizza Fest" did take place again at Roundtable 
Pizza. They made it real nice for all the 'Holers, and if you are 
ever in the area you should drop in and say hello to them. 
Their pizza is teriffic and the service is great. 

A few predictions for the coming months are in order. 
Expect to see a glut of used 512k Macs on the market. (Wow, 
breath-taking prediction here!) Macs and external drives are 
already selling used for under $1400, but with all the 
"Certified Developers" out there getting Mac+'s you can 
expect this to fall to under $1000 soon. I also expect the 
Mac to be the defacto standard for high-end (read: professional) 
music applications. — Mac and MIDI are a powerful 
combination, and as witnessed at the Winter NAMM 
convenention (a trade show for the musical instrument 
industry), everyone it seems is coming out with MIDI 
software for it. 

Finally, to get a password for the MouseHole, send a 
SASE to us at Post Office Box 2323, Orange, CA 92669. 
Currently there is about a 30 to 60 day lag, and we haven't 
forgotten about you (hopefully!). If you don't have a modem 
but you have something great to tell us, write! We enjoy all 
the cards and letters that just say hello. And thanks to 
everyone else who has written in the past. (You should see 
some of the great post cards we have gotten from overseas!) 
See you next month- Rusty. 


HFS & the FINDER 
From: KATZ 


I got curious what would happen with a lot of files on an 
HFS volume. 


Files in Root Time: Finder 
10 3 secs 
60 10 secs 
110 16 secs 
160 21 secs 
250 56 secs 
400 3.5 mins 


I put them into a folder and was back to 3 secs. If the 
folder was open it took about 10 secs for the FINDER to 
come up. So I guess the moral of the story is keep the root 
directory as close to empty as you can unless your in no 
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hurry. [Hard to do with all the buggy programs that don't work 
with HFS yet, and require various files in the root directory! - 
Ed.] 

Also I tried it with 1000 files and 30 minutes later the 
watch was still there! With 6000 files I got a message that 
said there wasn't enough memory to add another disk. I only 
had the one hard disk on line. All of the above times are with 
files 2K in length and all were in the root directory. 


FAST MAC & SCSI ROMS 
From: BOB DENNY 


I was talking to this guy from (name withheld) yesterday 
and he casually mentioned that HE didn't see the need for that 
darned 2 MIPS Mac they showed him... 

Uh, the Tecmar guy who wrote the Apple SCSI ROM 
code... well, seems that he %#4$@# it up royal. On "blind" 
transfers, he didn't test it with very many periphs and turns out 
it's got timing bugs. To the tune that disk vendors have to 
put a special patch resource in RAM for their disk type. I 
dunno what the implications are concerning multiple mixed 
device types on SCSI. [Note: a SCSI hard disk rep confirmed 
this to me, that Apple's impementation only works for the 
particular hard disk controller hardware with which they tested 
the thing, due to the "blind write" transfer. If you have 
anything other than that particular vanilla brand controller, 
you've got to patch the code. In effect, the SCSI disk 
developer's are currently debugging Apple's code on a day to 
day basis! -Ed] 


Faster than a speeding scrapbook.... 
JIM REEKES 


After using the standard 512k Mac with the HD20, I 
noticed a BIG slow down with the scrapbook. Well, after 
using the new Mac+ and the HD20 I noticed a BIG speed up 
with the scrapbook. In fact, now I can flip through the 
clippings faster than my eyes can read! Wow. Its 
unbelievable! 


SCSI Manager 
From: STEVE BRECHER 


I'm sure Erich is a fine fellow, but as noted by Bob, the 
128K ROM SCSI Manager is far from optimal code. I 
suppose you could consider the problem with "blind" writes as 
a timing problem; I see it as a logic error. "Blind" reads 
should work OK, except slower than they could be. 
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The MicahDrive (an internal hard disk, software by yours 
truly) uses exactly the same SCSI interface chip as the Mac+ 
external SCSI, and transfers data 2-4 times as fast as the 128K 
ROM SCSI Manager. 

I doubt the MacDrive is faster than a HyperDrive - 
- probably what was measured was HFS vs. MES. 
Benchmarking Mac disk hardware is tricky. 


128K ROMs 
From: MAC SPY 


Here are some measured ratios of old drawing speed to 
new drawing speed. 


Paragraph of Text 1.50 
CopyBits Aligned 1.35 
CopyBits (region -> rect) 2.30 
CopyBits Stretching, General 1.30 


CopyBits Stretching, selected ratios 1.30 
FillRect 1.44 
InvertRect 1.32 
Slanted Lines 2.29 
Verticle Lines (region -> rect) 4.98 
PaintOval 2.19 
FrameOval 2.14 
PaintROval 1.71 
FrameRRect 1.58 


The trap dispatcher has been modified to use unpacked 
long words instead of a packed format so of course the trap 
table was expanded to 2 tables. The OS table is at $400 - 7FF 
and the Toolbox table at $COO - 13FF. The ROM now uses 
bit 11 as the definitive way to distinguish between OS and 
Toolbox traps. This means that there are now 256 different OS 
traps (Ax00 thru AxFF, where x varies depending on 
parameter bits) and 512 different Toolbox traps (A800 thru 
A9FF). 

The 128K ROM includes many system resources that 
were RAM-based in the original system. 

DRVR 2 (Print), DRVR 3  (.Sound), DRVR 9 
(.MMP), DRVR 10 (.ATP), SERD 0 (serial drivers), CDEF 
O0 (button) CDEF 1 (scroll bar), MDEF 0 (text menus), 
WDEF 0 (standard window), PACK 4 (SANE), PACK 5 
(Elems), PACK 7 (BinDec) 


ResEdit 
From: DON L 


Try this one. Create a small graphic image in Draw or 
Paint. Copy it to the Clipboard and go to ResEdit. Edit an 
ICON or ICN#, (CURS and maybe some more) then do a 
Paste. Also, when editing an ICON hold the shift key down 
and drag the mouse to get a selection rectangle to cut or copy 
from the ICON. 

The version of ResEdit used was 1.0 DS. Don't know 
which older versions may have that capability. 
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Disk Cache 
From: KATZ 


I haven't seen any documentation for this but if you have 
the new ROM's, and the new control panel, the disk cache will 
work but only for an applications resources. All you have to 
do is set the applications cache bit with Fedit 3.5 and set the 
size of the cache with the control panel. Seems to work pretty 
smooth. [Note: Fedit 3.5 may have problems on Mac Plus 
systems. Try ResEdit 1.0d5 by selecting a file and doing a 
"Get Info" within ResEdit. You can then set the cache bit for 
the file. -Ed] 


MacExpo 
From: BOB DENNY 


I had a whirlwind day at the Mac show yesterday. Wish 
I'd stayed, but ... Odesta is showing their "Double Helix" and 
“Multi-User Helix". Both of these products knocked my socks 
off. Object-oriented databases are here to stay. General 
Computer is showing their HyperDrive 2000, a 20-mb 
internal disk with 1.5mb RAM & a 68881 hardware floating 
point chip. 

Consulair has a bunch of new stuff, including a rev of 
their development system which runs under HFS, the only one 
that does at present. Bill Duvall has set up a really nifty "path 
manager" which allows you to define various folders for 
libraries, "H" files, etc. It makes the HFS environment really 
go to work for you as a developer. Plus, Consulair's compiler 
emits code that supports the HyperDrive 2000 hardware 
floating point ( instead of slow SANE), as well as another 
memory upgrade's FP chip (I forgot the name). I can't WAIT 
to get my amber replacement CRT, also seen at the show. 
"Studio Session" is a RAD radio/tape with VU meters for each 
of channels ... it looks and sounds GREAT. "Orbiter" from 
the folks who brought you GATO, also fascinated me. It's got 
a data base of mission profiles, and carries you through a 
complete mission from launch to landing. 

On the APPLETALK front (near and dear to my heart)... 
I mentioned Multi-User Helix, a VERY slick adaptation of 
their "Run-Time" Helix where folks on various AppleTalk 
nodes can "visit" a database on one of the nodes, opening 
windows (forms) and viewing or updating the information. It 
has a cute record-locking mechanism that beeps the lock holder 
when another user wants the record, and the "Help" dialog tells 
the appropriate story ... Hayes unveiled a "half bridge", which 
allows you to connect two AppleTalk nets via an RS-232 
link, up to 9600 baud. Dial-in LaserWriters... We are looking 
at implementing the half-bridge protocol on our VAX so you 
can dial in and join an internet. There were the usual gaggle of 
wimpy disk servers, with one exception ... General Computer 
had their HyperNet there. It looked to be VERY well designed, 
supporting multiple accessors to a single volume/drawer. 
Anyone can "export" a volume, and EVERYONE else can use 
the files on it, including applications. Remote volumes act 
exactly like local ones. This product does NOT depend on 
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Hyperdrives. It works with most any disk, floppy or hard. Oh, 
yeah, only one "write" path can be open to a given file... 
multiple readers, single writer. 

At the AppleTalk developers conference a few days ago, 
there was a STRONG statement made that AppleTalk will be 
in ALL future Apple Products. Whew! [Good! -Ed] 


Desktop Reorganization 
From: GARY VOTH 


For all you HD 20 owners out there: It is a good idea to 
periodiclly reconstruct the Desktop file on the hard disk. The 
Macintosh Finder stores program icons and other information 
in this file long after specific programs have been deleted from 
the hard disk. (Ever wonder why a program will sometimes 
appear on one startup disk with an old icon? It's because the 
Finder uses the icon resource stored in the Desktop file instead 
of the current one stored in the program's resource fork. To 
see the new icon on that disk you must rebuild the Desktop 
file.) 

To "shake loose" this excess bagage from your disk and 
optimize the time it takes for the Finder to build the desktop, 
hold down the Command and Option keys simultaneously 
when booting up the system with the HD 20 Startup disk. 
The newest versions of the Finder now legitimize this 
command with a dialog: "Are you sure you want to rebuild the 
Desktop File on [volume name]? (This might take a few 
minutes.)" D. 

There is very good news indeed for HFS volumes: the 
Finder retains the names of all of your subdirectories (folders). 
You need never fear having to reconstruct all of the folder 
names on your HD 20. (This is not the case, however, on 
standard MFS formatted volumes -- you still get folders with 
Unnamed/hn, etc.) 

I've had my hard disk less than a month and I brought the 
Desktop file down from 48k to 33k in one fell swoop! 

To get an idea of how nicely constructed the new 
operating system is, take Fedit (versions 3.2 and later) and 
peek at the volume header information for the HD 20. Check 
out all of the volume caching fields. With RAM disk caching 
implemented on the Mac+ control panel, it seems Apple has 
gotten very serious about optimizing the performance of their 
little graphics workstation. Good show! 


Finder 5.1 Features 
From: DAVID EDWARDS 


This was a new one on me, while sleeping with my 
finger on the OPTION key, I closed a window and next thing I 
knew all the open windows on the screen started closing up... 

Boy was I surprised or had I missed something! It works on 
finder 5.1d4 with either a close box or using the file menu. 


From: GARY VOTH 


I discovered a really nice feature of Finder 5.1... When 
executing under Switcher, the Shut Down command changes 
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to Quit! Simply pull down the special menu and choose Quit 
when you want to exit. It also is "Switcher aware" in that it 
contains the parameter resource showing its optimum 
configurations; just double-click for a 192K Finder! 


Even newer Finder 
From: DON 


Personally, I think the most exciting thing I saw at 
MacExpo was not the new Mac, the MC68881 upgrades, 
amber monitors (remember mood watches anyone), or even 
that new paint/draw combo from the Silicon Beach boys. It 
was Andy Hertzfield's new Finder. Remember when he was 
down in Santa Ana two months ago talking about starting 
another project after Switcher? Well, he did. 

And remember Multi-Mac? Well, forget it. Andy took 
about 6K of his Switcher code and has built a new multi- 
tasking Finder around it. He had MacWrite, MacDraw and 
another program all up at the same time on a 512K Mac with 
his Finder peeking through in the background. The new Finder 
has a lots of nifty features too besides multi-tasking. And it's 
fast. 

Andy figures he'll be finished with the thing in mid- 
Summer. I asked him if he was under contract with Apple for 
the project and he said no. However, Apple (blue pin-stripe 
three-piece suits and all) will probably buy it anyway. They 
would be out of their minds not to. 

By the way, Andy also showed off his patches to MDS 
and the system file which allow it to work properly under 
HFS. This patch is really bizzare and actually has more to do 
with the system file than MDS. 

I think the man is some kind of mutant (in the good 
sense of the word), but if he keeps writing software like this, 
maybe we should ask the federal government to declare him 
some kind of national monument. 

By the way, if your writing an application now to run 
with background tasks under Switcher, it will work correctly 
under his new Finder. 


Amber Screen 
From: DAVID ROBINSON 


Who ever asked about the Amber screens here is the info 
straight from MacExpo: ORANGE DROP (S.AS. 
ELECTRONICS INC.) 1-800-331-8133. They only want $99 
to swap your tube (could be worth it for novelty sake!) 

Just a quick word, a friend of mine set me straight on the 
Green/Amber/ Black & White debate. He says that Green is 
the optimum in low light conditions, Amber is for High 
Light conditions. BUT»»»» It seems that everybody defeats 
the purpose by turning up the brightness so high that no 
matter which tube they have it hurts there eyes! 

ANSWER, don't bother changing your tube, just keep 
the brightness down to a reasonable level and allow your eyes 
to adjust to it. Take breaks every 15 min. and focus on 
something far away to relax the muscles in your eyes. 
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Mousehole Report 
Mac Plus 


Mac Plus excitement is building as upgrades finally 
become available. There have been rumors about a RAM- 
based version of the 128k ROM. This will make the 1-Meg 
and up Macs really fly without an expensive upgrade. We've 
also heard of high-density SIM boards available in Japan that 
are fully plug compatible with Mac's. Imagine 4-mb in your 
Mac for $500-$800! 

Add this to the abundance of SCSI hard drves coming out 
onto the market place. At last Mac will be able to compete 
price-wise with all the PC-compatible type hard drives! I've 
already seen 20mb Mac-SCSI drives listing under $1200. And 
they are so fast! 

Before we get onto the goodies for the month, I want to 
remind you that you can still get a password for MouseHole 
by sending a SASE to us at Post Office Box 2323, Orange, 
CA 92669. Rusty Hodge 

Mac Plus Keyboard 

From: GEORGE 

Yes, the Macintosh Plus keyboard will work on a 
standard 512K Mac. In Excel, both arrow keys and number 
pad function fine. In word, the numbers on the pad didn't 
work, but the cursor arrows do. It won't fit into your carrying 
case ( misses by about 3 inches ) Keyboards are optional 
upgrades and do not come with the logic board upgrade, so you 
can continue to use your old Mac keyboard on your upgraded 
Mac+. If you do buy the new keyboard ($139), you get to 
keep your old one, so it may be more convienient to travel 
with your old keyboard packed in the case. 

HFS Open 

From: GARY VOTH 

For those of you who don't yet know aout it, it is a patch 
to the System that forces the GetFile and (occasionlly) PutFile 
routines to do a directory tree search when passed a 
VolumeName:FileName reference. If the FileName is not in 
the root direcory, then Andy's patch keeps looking in 
directories until it finds it. The calling program never knows 
the difference! 

This works fine with Edit, TML Pascal, most of MDS 
(the transfer menus now work properly), the Sidekick editor, 
and even BASIC programs like Communique, which must 
rely on BASIC to handle disk I/O chores. The only drawback 
seems to be a bit of a delay as the search is taking place. 
Thanks a lot, Andy! 

(Also: Don mentions "Has anyone realized that the 
version of Edit shipped with the Consulair Utilities package 
works with HFS perfectly WITHOUT Andy's wonderful 
HFSOpen program?" [This is version 1.53 of Edit, shipping 
with version 4.53 Mac C packages. TML is also shipping 
version 2.0d1 of Edit from Apple with their 1.1 Pascal, which 
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is dated a few weeks earlier than the Consulair version. My 
guess is that since Bill wrote the silly thing, the Consulair 
version 1.53 is more solid than the Apple beta release 2.0d1 
despite the version numbers. Does anyone really know? -Ed] ) 

Amber screen 

From: BOB DENNY 

I am the proud owner of engineering sample #4 of the 
new SCS "Orange Drop" amber screens. Some of you may 
recall my complaints of eyestrain and "dynamic blind spots" in 
front of my eyes. Well, no more. I am sure that it's not so 
much the color as the near elimination of flicker. I had 
determined that the worst case was when I was in my 
fluorescent-lit office looking at the Mac. I could see the 
flicker clearly out of the corner of my eye. No more. The 
amber screen is more restful, but more importantly, 
undetectable flicker. It's really quite wonderful. 

New Fast Eddie 

From: RUSTY HODGE 

I've been using the "new" version of Fast Eddie [Edit 
alternative] and it seems to be an improvement over the 
previous version. It still is a bit slow when it comes to doing 
a lot of cutting and text manipulation (ie.- preparing 
MouseHole columns for MacTutor!) but really isn't any 
slower than Word. The switchable word-wrap is a nice feature. 

Fast Eddie 2 seems to be bug free, I've been using it 
instead of MDS Edit on my Tecmar (If it will crash anywhere, 
it will crash on a Tecmar... heehee). As Toolsmith said a 
while back, "when the bugs are out it'll be good". Well, 
seems like the bugs are out. It is nice to see several good 
editors available finally (Fast Eddie, QUED, and MDS), 
giving us a nice range of choice. 

Oh, almost forgot. A feature of Eddie I haven't goten to 
play with yet, "FastUser()"... this allows you to add Cmd- 
Option or even additional menu commands to the program, 
which can call any Fast Eddie or Mac routine and even be 
linked to your own Megamax C routines. Quite a novel idea! 

Disk Cache 

From: MIKE STEINER 

To use the disk cache on the Mac+, you have to set the 
cache bit on the programs (and maybe documents) you want 
cached. The only way I know of to do this is with Fedit 
version 3.5 (maybe 3.21 will do it too, but I'm not sure). 
Apple will have to come out with something for this soon. 
Of course you also have to set the cache memory with the new 
control panel. 

From: DAVID LAWRENCE 

I believe you can change the cache bit (among other bits) 
by using ResEdit 1.0D5. Just select the file you want to 
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change, hit command-I and select the appropriate bits to 
change. 

FLIGHT SIMULATOR 

From: TAX FREE 

Since it will become available in about a month [or as 
you are reading this -RH], and has several interesting features, 
I thought some would be interested in the specifics of the 
Microsoft Flight Simulator. I've been testing the current, near 
finished version for about 2 weeks. First, you have your 
choice of 3 simulations... Cessna 182, Lear 25g, or a WW1 
battle scene. All the planes have terrific digital sound! You can 
have up to three views at once. Besides direction out the 
window, you can plant a chase plane, follow your progress 
from the tower, etc. The refresh times are not that of Fokker 
of course, but they are not too bad. In return you get shading 
and all the rest. The sensitivity of the controls is quite realistic 
and completely adjustable. You can also simulate frequency of 
breakdowns, superb cloud and weather conditions, and a so 
many other new features they couldn't get them into the 
already complete manual. IFR....Absolutely complete 
instrumentation, including DME and ILS. The simulation area 
covers 10,000 x 10,000 square miles, 118 airports...the US, 
parts of Canada, Mexico, Carribean, etc. The simulation 
includes fairly accurate buldings (try to fly the Lear between 
the Towers!). And they're still adding more features up til 
deadline. It is fairly solid already. 

Im using a Quickstick with it, and much prefer it over 
the mouse, though the mouse is OK, it's is not as effective as 
on Fokker. But the simulation is far more realistic the Fokker. 
Worth buying for sure. 

Crashing the HD-20 

From: GARY VOTH 

I managed to crash my HD 20 no less than three times 
in the last week - not hardware crashes, but system software 
stuff. I thought I'd pass along my experiences to the rest of 
you. 

First, if you manage to trash your system file or the 
Finder, simply boot the system with the HD 20 Startup disk 
while holding down the mouse button. This forces the floppy 
to become the startup volume. You'll then have to do surgery 
on your System file on the hard disk. Safest is to simply 
copy over a backup of the System file to replace the damaged 
one. Same goes for the Finder. 

Secondly, if you find you have trashed your desktop file, 
you may not be able to rebuild it by holding down the 
Command & Option keys on startup unless YOU HAVE THE 
5.0 VERSION OF THE FINDER installed on the HD 20. 
Yes, I know we've gone over this before, and someone 
mentioned problems with system crashes when trying to 
rebuild the desktop file. It seems that an incompatiblity exists 
between Finder 5.1 and the HD 20 OS patches that causes 
this problem. I have had no problem when using the older 5.0 
Finder. 

Finder 5.0 and up Bug! 

From: DON 

While working on a DA for MacTutor, I discovered a 
rather bizzare bug with the new Finders (5.0 an above it 
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seems). The bug goes something like this: 

If a call to GetMenu is made during the operation of a 
DA, and the MENU resource being called is already on the 
heap, the Mac will crash -- BUT ONLY ON THE OLD 64K 
ROMS while using Finders 5.0 and above! 

The reason is not simple, and took over 4 hours of 
tracing through the ROMs with TMON to discover. 
Apparently the new Finders jump directly in and out of the 
ROM at absolute locations, because during the errant call to 
GetMenu, Get Item is also called and on exit does a JSR (AO) 
to a location above the 64K ROM image -- apparently into a 
not existant 128K ROM routine. 

Although I cannot confirm this, the new Finders also 
seem to be doing strange things to the trap dispatcher, as well 
as patching other ROM routines -- especially in the Resource 
Manager. 

HD 20 Backup/Restore 

From: ABDUL 

Oh the pain...The agony... 

My HD 20 just got a case of Creeping Folder Leprosy. 
One by one, folders became inaccessable. The Finder 
complained that there was not enough memory to open the 
folder and the file open dialog box in applications refused 
(without any comment or error) to open these diseased folders. 
Trying to rebuild the DESKTOP won me a "Can't complete 
this operation because of disk errors"!!! 

After rescuing a couple of newly created files I turned the 
HD 20 Diagnostic loose in DESTRUCTIVE testing mode (no 
errors found!) and rebuilt the disk. 

Things look fine now but... Having worked with large 
systems for most of my life I now feel very very 
uncomfortable using a system with no backup/restore utility. 

SCSI HD-20 [ie new Apple product...] 

From: MAC SPY 

It is 2" thick compared to 3" for present HD- 20. No fan. 
Its quiet. Uses a Rodime 20 meg 3 1/2 drive with SCSI 
controller built in. Also, no upgrade planned for present HD- 
20. Going to be 2 different models. Keep this a secret, OK? 
[Sure...] 

Rumors, Rumors, Rumors 

From: HIGH ORDER BYTE 

Here is some more info for you guys. Apple will not 
ship any upgrade kits until the Mac+ stops selling so well. 
Apple makes tremendous profit from the Mac- and almost 
nothing on the upgrades. Sculley is hard-nosed about putting 
all the ROM's into the Mac+. Forget about the people dying 
for upgrades! He wants the stock up! 

The current ROM's in the Mac- are not the final version. 
Supposedly, the ones being produced right now ARE the final 
version. I don't know how to tell, or if you will be able to 
Swap. 

Finally:: Hosiden Electronics in Japan got an order from 
Apple for 100,000 circle-8 connectors (which we call DIn 
plugs). Nobody makes them anymore, including Hosiden. 
March 1st they had sent Apple 4,000 connectors to date. 
February 20th, Apple has increased their order from 100,000 
to 1,000,000. Exactly 10-fold. I think this might be half the 
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reason the upgrades are so slow in coming out. Hosiden 
doesn't care much for them because they are not making much 
money on them as compared to the color LCD flat screens 
they are making for commercial airliners as TV's. (and maybe 
a few computer companies?) 

HFS & Microsoft 

From: MIKE STEINER 

It appears that when using Microsoft Word, Multiplan, or 
Chart with HFS, the invisible protected files cannot be in a 
folder. Even with Andy's HFS fix, they still have to be out of 
the folders. 

From: CHIEF WIZARD 

I was able to put the invisble files into a folder as long as 
they were in the same folder as the application they ‘protect’. 
The problem I had was making the file invisible and protected 
AFTER it was in the folder. The way I finally did it was to 
open the HFS volume (in this case, an Apple HD20), with 
FEdit, and modify the bits directly. This is a little bit tricky 
because the directory arrangement isn't the same as MFS. 
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SCSI notes 

From: BRETT 

I had wondered why apple had a 25 pin connector for their 
SCSI port until this weekend when we finally got our SCSI 
cables. They externally convert to a 50 pin differential 
connector to become compatible with the rest of the world. 
And here I thought Apple was trying to start a new standard. 
Apple??? 

UniDisk on the Mac 

From: VIDEO WHIZ 

To hook up a UniDisk 3.5" for an Apple //, just take 

the external drive cable from your 400k drive, and plug it into 
the MECHANICAL ASSEMBLY of your UniDisk drive. 
You MUST bypass the analog card inside the UniDisk to use 
the drive on a Mac. You kinda have to take a lot of the 
UniDisk apart to get at the connector on the mech. assy. This 
disables the eject button on the UniDisk, as well as the LED 
"jn use" light. 
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Mousehole Report 
Update Problems 


Who gets the file (STD) 
From: TIM HEWITT 


I am proposing a standard way to deal with program 
owned data files under HFS. I am talking about files not 
specifically opened and closed by a user, (Red Ryder's ‘Stuff 
file for example). Here it is: On your distribution disk, place 
the files in your suggested folder hierarchy. When you open 
that file in your application, specify the pathname you set up 
in the first place. If you do not find the file where you expect 
it to be, put up SFGetfile's dialog (prompted of course with 
the file name you're looking for) and have the user find it for 
you. Now save this pathname as the current location. Next 
time you need this file, look here first, if not found put up 
SFGetfile.. (there is a pattern here folks). The user will 
Soon get the message and not move the files around 
unnecessarily. This eliminates the need to have support files 
in the 'Blessed' folder or the root volume, and does not require 
you to force a certain desktop arrangement. Further it keeps 
you from having to search the entire hard disk for the file in 
question, (is the first one you find the right one to use?). Any 
comments ? 

I have implimented this and it seems to work very well. 
I would like to propose this as an extension to the standard. 
What do you think? The code to do this will be published in 
an upcoming MacTutor article. (Dave Smith permitting. 
Where is my Authors Kit anyway?) 


Finding Files 
From: JIM REEKES 


I will be so bold to recommend that all DA's should AT 
LEAST presume that their supporting files are located in the 
System Folder. This should cure al ot of the DA problems 
with HFS. The DA shouldn't have to look through every 
folder on the hard disk. It should only have to check the 
System Folder. 

Also, has anyone seen a version of the ImageWriter // 
driver thats works in standard mode? Everyone I've tried has 
problems. If you think you've got one that works, then try 
this test: 

A) Go into MacWrite, and type a page full of "H's. 

B) Now print it in Standard mode on the ImageWriter //. 

C) This should have printed in Bi-Directional mode. 

Notice the bad alignment? Apple recommends using the 
ImageWriter / driver till they fix it. 
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Consulair news 
From: DON 


Just talked to Jay Friedland of Consulair Corp. this 
morning. For those of you writing DAs in Mac C, there is 
good news. A linker option is coming that will create a 
DRVR resource and header, and include a library of glue 
routines to the C open, close and control functions. Until that 
time (probably early Summer, but I didn't get a firm date) 
Consulair will continue to ship DeskMaker. However, they 
will also be shipping my DA header and macro source, shown 
in the April issue of MacTutor, as an alternative. They might 
also ship some other glue routines written by a few other 
folks. I think they'll put this stuff on one of the examples 
disks, but I'm not sure. If you're interested in a particular 
implementation of DA glue routines, now is the time to write 
Consulair and tell them. But don't worry too much, whatever 
they finally wind up using will be provided in source form for 
re-compilation. For application programmers tired of writting 
all those glue routines for packages and Pascal calls, Bill 
Duvall is working on the finishing touches of a library which 
will cover ALL the functions now missing in Mac C. Bill is 
actually working from a variation of the library compiled and 
written by the B.M.U.G developers group. The source to this 
library is already available on MH DownLoad. I'll be testing 
these new products, so I'll let you all know what's going on as 
Soon as I can. 


Warp Nine 
From: ISOEMAC 


Beware of Warp Nine Engineering. They are selling a 
800K disk drive for the Macintosh. I ordered one these drives 
on 4/2/86. The salesman, Paul Hendrickson told me that they 
would ship the drive on 4/4/86 or no later than 4/7/86 second 
day UPS. I called Warp Nine on 4/7/86 to confirm shipment. 
My drive did not come today(4/9/86). I called Warp Nine once 
again, this time they told me the drive was not shipped and 
that they were "backlogged." Warp Nine also demonstrated 
other poor business practices that I cannot describe. If you 
choose to deal with these folks...caveat emptor! 


Publishing Show 
From: MACOWACO 


Just got back from the show at the LA Convention 


Center. Apple had a big booth with displays of some real nifty 
stuff. 
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1. MacServe. Yeow. We are buying it. It looked great. 
After an hour of hacking away with opening volumns closing 
volumns playing eith the security stuff and experimenting to 
the sales persons’ delight I'm sold. I should get my copy 
tomorrow FedXd. We will be trying a netwrok with about 10 
+s and 3 HD20s all with MacServe. Hot Stuff! 

2. InBox (Emial) My first imprressions during the sales 
pitch were initially more favorable then MacServe. 
Narrowcasting as well as Broadcasting of messages was easy. 
One can even send a message to a predetermined group of 
nodes. A paperclip function lets the sender send a memo with 
a file or an unprotected app. The server holds the stuff till the 
user signs on. Received message indication across the menu 
bar and more. I was about to say WE WANT IT when I 
noticed a Mac at the end of the line which had a strange dark 
display up. I asked the lady what was on it and she said... 
Oh.... thats the Mac which is the dedicated MMail holder. You 
guessed it the damn thing needs it's own Mac and HD!!! I 
walked away. There was also a giant size Laser printer 
(nonApple) which ran Postcript. Pagemaker was printing from 
it full newspaper sized pages with a much higher resolution. 

The AST Drive was also there 70 Megs and all and 
hooked up to the SCSI. I found it when I asked the guy why 
the Mac I was playing Macserve on was loading stuff so fast 
off its own volumn. It was hooked to the AST which had a 
MacServe manager on it. Funny the crowd around the Apple 
booth was at least comperable if not larger then the crowd at 
Xerox. All the others were as good as empty! That is except 
for Interleaf. They had the largest crowd. 


LaserWriter Incompatibility Blues 
From: LASER DOLPHIN 


LaserWriter and LaserPrep 3.0 are NOT COMPATIBLE 
with many popular applications. These include, by my own 
experience, Microsoft Word and Excel. I have not tried but 
have heard that the same problem (described below) occurs 
with Apple's own MacWrite and MacDraw. I STRONGLY 
RECOMMEND THAT YOU STAY WITH LASERWRITER 
DRIVERS VERSION 1.1, even if your friendly tech gives 
you 3.0 along with System 3.1.1. I am now running all my 
applications with System 3.1.1 and Laser drivers 1.1. I have a 
512K Mac with the new ROMs. The problem is very simple 
and completely intractable. It also makes the 3.0 laser drivers 
totally useless. What it does is this: it ALWAYS calls for the 
Mac to send a bitmap of the font -- EVEN IF THE FONT IS 
A LASER FONT. The results are singularly ugly, jaggie- 
ridded Times, for example. [Note: I haven't had this problem 
running Laser drivers 3.0 on a Mac Plus with system file 
3.1.1. See next note. -Ed] 


From: JIM REEKES 


I just spoke with the tech support staff at Apple. They 
tell me that your problem with the laser is the font file. Strip 
all of the fonts out of your system. MAKE SURE YOU'RE 
USING F/DA MOVER 3.1!!! Then get the latest version of 


524 


the laser fonts and re-install them. 

Seems that there is a new format for laser fonts. FONT 
FAMILIES.(?) One font (ie TIMES) comes in all sizes, but 
there is only one family. Some weird things happen if you 
have the old set of fonts on your disk, or if you try to install 
Just one new size for a given font. But anyway.... strip all of 
the fonts out, then install them. Make sure that you do use 
F/Da Mover 3.1, this is the ONLY version that can handle 
fonts properly. I've tried to duplicate the problem with our 
Mac, but couldn't. So it must work. 


Red Ryder 
From: GARY VOTH 


[There has been an ongoing discussion of terminal 
software on MouseHole. With the latest update to Red Ryder, 
it of course sets itself for being picked on this month. Some 
of the discussion is presented here for the sake of anyone about 
to dive into the wide world of telecommunications. - Rusty] 


We have now established that Red Ryder is: 


a) The most wonderful program ever written, 
b) A worthless piece of garage software, 
c) May work OK but is damn ugly. 


For those of us who fall into the 'c' category, I can say 
that we can agree to disagree. Since RR is not a commercial 
application, I have no real reason to complain about it. If you 
want slick packaging and program design, you should 
probably expect to pay for it. If RR fits your needs, then fine. 
It just doesn't seem in the spirit of the Macintosh, which had 
graphic design people among the software and hardware 
development team from the begining. 

The original Mac application and document icons are 
good examples of this: spartan and elegantly representative of 
their purpose. Since then icons have become prolific and 
ugly. (FKEY Sampler is my favorite.) The whole idea was 
to have a few standard graphic sybols that would be 
immediately recognizable as to their intended purpose, not 
junk to clutter up a menu bar. 

By the way, if you are interested in seeing a truly nice 
user interface on a terminal program, go into your authorized 
Apple dealer and ask to look at AppleLink in action. Apple 
has licensed this whole system to GE Information Services 
Corp (or some such) to be marketed as BusinessTalk. The 
whole package was contracted by some guy up in the valley. 
Can't remember his name. If anyone knows, post it. 


From: LASER DOLPHIN 


Red Ryder is homely, but it. works. I haven't compared 
the xmodem transfer speed with other applications, but if it's 
slow, SW should hear about it until he fixes his algorithm. 
As for the misplaced filing menu items, he's already heard 
about that from me on CompuServe. I hope everyone yells at 
him about that. 
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Scott seems to have all the business sense of the average 
sea slug. He preaches at the converted and threatens the rest. 
He doesn't seem able to keep a simple mailing list of his 
valuable shellers-out of $40; some people got no 8.0 notice, 
while others seem to have gotten 2, 3, or even 4 identical 
notices. 

I have, however, found Scott to be receptive of criticism 
and dedicated to improving this product. Why should I buy 
Microphone for $80 when $40 gets me Red Ryder. Yes, I 
paid for revision 7, and I got one and exactly one 8.0 notice. 


From: THE DJIN 


Opinion: Red Ryder is powerful but like all users I have 
complaints. Obviously time has been spent incorporating 
features for the most users and a splendid job has been done. If 
only the size could be cut down. Slowly my disks have 
become inpractical as all his message screens are added to the 
program. Is it possible to remove these easily? The transfer is 
one of the lower in bullet proof. I must switch out of it most 
of the time and run old faithful Telescape to receive what I 
want. (It is the best transfer system I have come across to 
date.) And last I must agree with the majority it is by far the 
ugliest display I have seen on a communications package to 
date. 


PageMaker/HFS/LaserWriter (not +) Incompatibilit 
From: LASER DOLPHIN 


If you use PageMaker 1.1 with HFS (say on a 512K Mac 
with a ROM/drive upgrade), it will fail to find a LaserWriter 
on the network. It will display a dialog that says that it is 
now defaulting to an ImageWriter print. This dialog LIES. 
What it is actually going to do is to try to print to a 
LaserWriter named "LASERWRITER" -- yes, that's right, 
ALL CAPS. Someone at Aldus must program on an Apple 
][+. Now, I like to call my LaserWriter "Creideiki, and 
hardcoded names for namable devices tend to tick me off. I 
suppose the rules weren't good enough for Aldus, so now they 
have an incompatibility in a $495 program. Arrogant twits. 
[The new 1.2 version supposedly fixes all these HFS related 
ills, although I have not been able to confirm this yet. -Ed.] 


Pagemake Update 
From: MIKE STEINER 


Pagemaker 1.2 is out as a free upgrade for registered 
pagemaker owners. It works with the lazerwriter +. The plus 
upgrade is only a collection of fonts. But, there are 512K 
worth of those fonts. As for whether it is worth the $800, 
that is up to you. If you have a need for them, it is worth it, 
and if you don't, it ain't. The local newspaper here that bought 
two lazerwriters thought that the new fonts were worth it, and 
they bought two upgrades. One reason for the cost is the 
royalties on the copyrights for the fonts. Apple has to pay 
those royalties for every upgrade sold. 


O The Complete MacTutor, Vol. 2 


HFS Bug? 
From: DON 


I just received my HD20 yesterday and discovered a bug 
with ResEdit or perhaps the HD20 Startup System ... I'm not 
sure. I've been using HFS for over a month now. I've had no 
problems on my Mac512 and 800K external drive with 
ResEdit, but hooking up the HD20 gives it fits. ResEdit on 
the HD20 will not correctly open files in any directories 
except the root and System Folder. If files in any other folders 
are opened they will appear empty, and an empty file of the 
same name will be created in the root directory. This file wiil 
only become visible after exiting to the Finder. Does anyone 
on the Hole know if this problem occurs on the Mac? Also, 
Psion Chess will not work with the HD20, however it works 
fine on an HFS 800K disk. Any clues? 

-- Confused but with a lot of storage, Don 

[I have ResEdit 1.0d7 on the MacPlus and it works fine. I 
don't have an HD-20 however. Note: We have recieved several 
reports of problems with the HD-20 crashing and requiring re- 
formatting. Until the software settles, beware. -Ed.] 


Naming Resources 
From: ANT KILLER 


In the March MacTutor Jan Eugenides asks how to name 
a resource with RMaker, its like this: type DLOG 
PutTheNameHere,-15999 

Just put it right before the ID#. That's it. 


HyperDrives Status 
From: GEORGE 


All HyperDrives as of the 18th are HFS/Mac Plus 
compatable ( in fact General Computer used Finder 5.2 to test 
their software ). The LIST price of a 10mb Hyper is now 
$1,395 and a 20 is $1,695. Installed Hypers can upgrade to 
HFS ROMs and up their 10 to a 20 now also. 

Hyper 2000 is also shipping : 12mhz 68000 with no 
wait states, 68881 math coprocessor ( Consolair C & 
Microsoft Excel are being recompiled to go to the 68881 ) and 
an additional 1 1/2 meg RAM. ( on a Mac4 that means 2 1/2 
megabytes ). 


SkipFinder6.0 
From: ISOEMAC 


There is a bug in SkipFinder6.0 while using it with 
MFS. If you select "Other..." for an application that has no 
documents, the "Print" button will flicker and the mouse 
button becomes inactive. I have discovered a solution that 
will return you to the main SkipFinder window. Simply hold 
down the option key and the mouse button becomes active 
again. Oddly enough, this problem only occurs when I am 
using MFS. This bug has not occured during the use of HFS. 
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Mousehole Report 


We're Back! 


In case you didn't notice, we were gone last month so 
that we could play catch-up with our period of down time to 
switch operating systems and software on MouseHole. 

By the time you read this, well be running under 
ProDOS with the latest version of the SnAPP Electronic 
Messaging System. In case you're not too familiar with the 
old Apple //, the older operating system, DOS 3.3 is quite 
wimpy compared to ProDOS. (ProDOS is quite similar to 
HFS on a low level. DOS 3.3 is akin to MFS running under 
Finder 1.1g). So we're now faster and have more effecient 
storage. 

Why don't we run MouseHole on a Mac you ask? A Mac 
is a terrible thing to waste on running a BBS 24-hours a day. 
MH runs on an old Apple //* in the utility closet at our 
office. It has no monitor, just a Silentype printer (remember 
those?) that spews forth reams of log information. Exciting, 
huh? 

Onto the good stuff. There are rumors of the Cad-Mac 
floating around. According to some, it has a 17 inch screen 
but the same pixel per inch density of the current Mac. You 
can have several applications open at once in the size of 
normal Mac windows, with plenty of left over room! 

This month we have a lot of bugs and oddities to report. 
This is expected to go on for a long while; I wonder if the 
whole (Mac) world will be moved to HFS by Christmas? 

The debate over the best terminal program goes on. Red 
Ryder is taking a lot of abuse, but if it was really a bad 
program, no one would care enough to talk about it, right? 

-Rusty Hodge, Sys. Op. 

Finder Quirks 

From: Laser Dolphin 

Finder 5.2 normally makes 400K disks MFS (non- 
hierarchical) volumes. Even if you have formatted a 400K 
disk with the Option key down, thereby making it an HFS 
volume, when you copy that volume in its entirety onto 
another 400K disk, the target disk is a flat volume with "little 
pretend folders" instead of true subdirectories. 

An undocumented feature of Finder 5.2 is that, if you 
hold down Option when copying one 400K disk to another 
(by dragging the disk icon onto the other disk icon), the target 
volume will become an HFS volume, regardless of whether it 
was formatted that way in the first place. 

From: MAC SCOTTY 

In Finder 4.1 versions and later there is a resource called 
"LAYO". You can edit that resource with the ResEdit and 
tell the Finder not use ZoomRects when opening and closing 
windows or when launching programs. You can also tell it 
to have Icons always align on the grid so you don't have to do 
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a cleanup all the time to straighten things out. You can also 
tell the finder not to ask you if it's OK to throw something in 
the trash or not, I get tired of having to remember the option 


Consulair news 

From: DON 

Just talked to Jay Friedland of Consulair Corp. this 
morning. For those of you writing DAs in Mac C, there is 
good news. A linker option is coming that will create a 
DRVR resource and header, and include a library of glue 
routines to the C open, close and control functions. Until that 
time (probably early Summer, but I didn't get a firm date) 
Consulair will continue to ship DeskMaker. However, they 
will also be shipping my DA header and macro source, shown 
in the April issue of MacTutor, as an alternative. They might 
also ship some other glue routines written by a few other 
folks. I think they'll put this stuff on one of the examples 
disks, but I'm not sure. If you're interested in a particular 
implementation of DA glue routines, now is the time to 
write Consulair and tell them. But don't worry too much, 
whatever they finally wind up using will be provided in 
source form for re-compilation. 

For application programmers tired of writing all those 
glue routines for packages and Pascal calls, Bill Duvall is 
working on the finishing touches of a library which will 
cover ALL the functions now missing in Mac C. Bill is 
actually working from a variation of the library compiled and 
written by the B.M.U.G developers group. TIl be testing 
these new products, so I'll let you all know what's going on 
as soon as I can. 

Warp Nine 

From: ISOEMAC 

The Warp Nine external 800k drive is professionally 
packaged and there was a handwritten evaluation of the unit in 
the box. The Phaser 800K has all of the features of Apple's 

drive and it comes with a manual eject button. I have run 
several tests using both HFS and MFS and the drive works 
flawlessly. It is also extremely quiet. I have found that this 
drive is one of the best MacValues around. They also offer a 
one year warranty for $29.00 and a 30 day money back 
guarantee if not satisfied. If anyone is interested, Warp Nine 
can be reached at 800-328-6795 ext 433. 

MINIDINS 

From: ROGER STEWART 

The famous 8 pin Minidin connectors can be found at 
HB Associates (800) 423-3014. 

ROM revisions (again, sigh) 

From: STEVE BRECHER 

At 400002, EE = Lonely Hearts (original) F4 = 
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Lonely Hearse (rare) EA - Lonely Heifer (final). Two bytes 
of code changed (between Hearts and Heifer -- hardly anyone 
has Hearse) seems too little to get worked up about. [Hmm, 
if it was enough for Apple to pay the big $$ to make a mask 
change, it must have some importance...-Ed.] 

An Upgrade for us ‘Lonely Hearts'? 

From: HIGH ORDER BYTE 

I heard a rumor that Apple was going to make an upgrade 
available for people who have the older version of the ROM's. 
This is only rumor though. I can't see Apple charging the 
consumer to fix their own goofs. That's why I don't think it 
will ever happen. Wouldn't later versions of the System 
and/or Finder have patches to the ROM's for any serious 
bugs? 

Every time a new version of something comes out, I get 
warnings of it. Like Systems 3.0. "It has bugs... use 3.1". 
Then I read Cserve and Apple condemns 3.1, and says to use 
3.1.1. Then, I hear 3.1.1 has problems like trashing system 
files. Then, I hear that the 'NEW' Font/DA Mover 3.1 had 
problems too. [Aldus just sent a postcard to all Pagemaker 
registered owners that says that 3.1.1 can trash Pagemaker 
files and that Apple is working on it...-Ed.] 

Is it safe to use ResEdit to cut and paste these DA's in? 
What's the deal with Apple? I mean, G's. Makes me feel like 
going back and using Finder 1.1g and System .97. (Well, not 
really) 

ResEdit D11 

From: JIM REEKES 

Can someone explain what this means..... Hold down 
the Command-Shift-Option keys and choose ‘About 
ResEdit..." What does "PIG Mode On" mean? Do it again and 
it makes "PIG Mode Off" PS, I wish I could claim 
discovery of this, but it was passed on to me by ‘The Lone 
Falcon'. 

ResEdit 1.0D11 Easter Eggs 

From: LASER DOLPHIN 

Various interesting "features" of ResEdit 1.0D7 and 
1.0D11: Pig Mode <toggle Pig Mode by holding down 
Command-Option-Shift and selecting "About 
ResEdit">; When Pig Mode is ON, a 512K Mac with new 
ROMs takes much longer to open resources, and keeps the 
drive running "forever" when a resource has been opened. On 
a Mac+, ResEdit with Pig Mode on simply will not open 
resources, giving an error dialog instead. WHAT THE HELL 
IS PIG? Option-Command plus selecting "About ResEdit" 
gives an acknowledgement box instead of the standard About 
box. The standard About box has a picture of a bullet in it. 
If you have used the Chooser DA to give your system a 
name, that name appears in the case of the bullet. There's 
only enough room for about four characters. Is Apple saying 
there's a bullet with your name on it? The various About 
boxes are in ALRT resources 144, 145, and 146 in ResEdit 
1.0D11. Happy hacking! 

Servant? What's Servant? 

From: DON 

How ‘bout that Andy Hertzfield anyway? Remember a 
few months ago I told you all about a new Multi-Mac like 
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version of the Finder that Andy was working on? Well, he's 
got a name for the thing now: Servant. According to my 
sources close to Mr. Hertzfield and inside the big Apple, 
Servant is now about 40% complete. It pretty much has all 
the Finder's functions plus it of course allows multiple 
applications to reside in memory and on the desktop at the 
same time. It is also only about 30K! No kidding. It requires 
at least a 1 meg of memory though. Last month (I think) 
Andy sold the first-look-at-the-source rights to Sculley and 
Co. for a mere six figures. He retained 100% of the 
publishing rights to Servant. Apple has the ball now. Andy 
told a Bay area users group that Apple plans to create a new 
Finder using Andy's ideas. If Apple does it right, Andy won't 
interfere or complete Servant. He's unofficially giving Apple 
a month to come up with something, but he says he thinks 
our friends in Cupertino are going to screw it up. And if 
this too comes to pass, he's going to complete Servant by the 
end of '86 and sell it for about $40. Expect freebie betas to 
appear by the end of July though. Overall I'd say this is pretty 
good news. 

The main problem between Apple and Andy seems to be 
that Andy has a much grander view of what an operating 
enviroment for the Mac should be. When Servant is 
complete, Andy feels it should also have a resource editor built 
right into it. Along with some other features, which I'll 
mention in a bit, Andy says Servant will wind up at about 
70K. It eats a lot of memory though, about 100K for screen 
buffers alone. Personally, I'm not losing sleep over lost 
RAM. 

By the way, Servant is at minimum, 4 times faster than 
the present Finder. Andy acomplishes this by not using the 
Resource Manager, and since he wrote most of it I suppose he 
can get away with this. Since the Finder bogs down keeping 
track of too many resource maps, Andy's Servant 'unwinds' 
all resource information into one gigantic array for easy 
traversing. No, I'm not sure what this means either, but this is 
how it was explained to me. Anyway, Servant is fast. 

Servant will also have a dandy query function. With this 
you'll be able to search and sort files quickly on huge HFS 
volumes. 

Andy is also one-upping DAs by introducing 'Servant 
Tasks, functions that can execute in the background. This 
means downloading, print spooling and other stuff. Andy 
may even do away with the 'Apple' menu altogether and place 
DAs as icons on the desktop. It boggles the mind. I'll keep 
you posted on further developments. 

Tecmar's TDISK 

From: BEAKER 

News from Tecmar: TDisk, Tecmar's SCSI hard disk for 
the Mac+, has been "temporarily" suspended. Originally 
targeted for release 2/28, then 4/30, problems finding a 
"reliable 3 1/2 drive" caused the delays. The reason for the 
suspension wasn't told to me. Although I can't say much 
about it, there is an alternative product that is receiving alot 
of attention at Tecmar. Let's say "it requires the MacServe 
software to be really useful." (and I quote). It's big and fits in 
the OLD MacDrive cabinet. Drives are half high, using a 
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new controller, and the current large capacity (can't say) can be 
doubled by putting another drive in the cabinet. Can't say any 
more. You didn't hear it from me. 

MELTDOWN! 

From: PAUL HELLER 

Got a Plus and ImageWriter 2 the other day ... about an 
hour after I got everything set up, I was fooling with the Mac 
when I heard some spitting sounds coming from the direction 
of the printer. I looked over to my left to see a really scary- 
looking cloud of white smoke billowing out of the 
Imagewriter, accompanied by spitting and popping noises. I 
lunged for the power cord, yanked it, and pulled the cover off 
the printer ... by this time the room was filled with acrid 
smoke. Seems it was the paper feed motor on the left side; it 
sizzled when I touched it with a wet finger, and the plastic 
nearby was getting soft. No doubt this is just a spectacular 
case of infant mortality ... but it's sobering. I don't think I'll 
leave my printer on overnight anymore ... 

Red Ryder Opinion 

From: GARY VOTH 

I have kept silent about Red Ryder for many months 
while others have sung it's praises here and in print. It has 
achieved something akin to cult status among Macintosh 
devotees. Those in the know say that the program's author, 
Scott Watson, is the only major "shareware" author for the 
Macintosh that has made any money. That may be, but in 
my opinion, RR is the ugliest Macintosh program in wide 
use, and one for which I would not pay for. — At the risk of 
tooting my own horn (and making enemies out of sóme of 
you RR buffs), my own shareware program Communique, 
which is written in interpreted BASIC, is miles ahead of RR 
in terms of its user-interface and "style" of operation. I'm 
NOT suggesting that Communique, which is intended for 
novice to intermediate users, is as powerful as or can 
substitute for a program like RR, but only that Red Ryder 
could be brought a long way towards respectability by its 
author. John Dvorak once wrote in InfoWorld that Scott had 
complained to him that he has sold a few thousand copies of 
RR but that he never gets mentioned in the magazines. I 
think if you look at the program you will see why: It is 
written BY a hacker FOR hackers. 

If you were using ASCII Express, you probably fall into 
the "power user" category. My recommendation would be to 
check out both the — HFS-compatible version of Hayes's 
SmartCom II, and MicroPhone, which I believe is being 
distributed by Software Ventures. — SmartCom II is simply 
wonderful. It is non-intimidating enough for beginners (even 
to the point of being "cute"), but has a powerful auto-pilot 
facility with which you can automate most of your tele- 
communications. MicroPhone (which I haven't yet seen) is 
written by Dennis Brothers, author of MacTEP and creator of 
the MacBinary protocol, and is said to be very powerful. 
Brothers, who may be the ultimate Mac telecommunications 
hacker, seems to have gotten his "human factors" right on 
this one too. Both of these packages offer TTY and DEC 
VT-100 emulation. Neither will work with synchronous 
3270 protocols; keep MacTerminal around for that. I think 
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they're the best general purpose terminal packages around, but 
there are others that offer a wider variety of emulation modes. 
Telescape from Mainstay is one. InTouch is also good. 
Tekalike offers Tektronics graphics terminal emulation, should 
you needit. Good luck. Gary. 

From: MAC SCOTTY 

I think that RedRyder is simply the best package 
available! It does everthing you could possibly want to do. It 
sounds like someone may be jealous of Scott Watson's 
program!! 

From: DON 

Heres my two cents worth on Red Ryder .. Scott 
Watson's Red Ryder has got to be one of the ugliest damn 
Mac programs I've ever seen (the original version of 
MacNosy being the worst). Being a professional graphic 
designer, illustrator and typographer, I think I can say this 
with some confidence; RR's menus are poorly organized and 
cluttered with icons, making it difficult to read and use. Its 
menus are also poorly worded, making them confusing. RR 
has an inconvenient method of editing macros. Using RR is 
not completely intuitive. I can go on and on, but ... Red 
Ryder works! And it works well. Its supported and it's 
constantly being improved by its author. It might just be the 
most powerful terminal program available for the Mac. 
However, I don't use it. Why? Simply because it's ugly and 
poorly organized. I'm sorry, but even a product as powerful as 
RR is dimmished by bad design. I use Dennis Brothers' 
MicroPhone. MicroPhone is not as powerful as RedRyder. 
Even Dennis Brothers would admit that. However, when I 
first received even a beta copy of MicroPhone, in less than 
fifteen minutes I had written three macros for my favorite 
BBSs. The release version is even easier to use. I still can't 
get RR to work properly. The macro utility works better now 
in 8.0 but its still incredibly stupid design. Yes, stupid. 
Thinking about it again, perhaps I was wrong about which 
program is more powerful. ^ Anyway, it's someone elses 
turn on the soapbox now. -- Don 

RR AND RRH 

From: SALTY DOG 

Ive been using Red Ryder since 5.0 came out and 
absolutely love it. The versions 7.0 and 8.0 have an 
excellent macro recorder. All versions have been most 
reliable with MacBinary and Xmodem/CRC. The program is 
easy to use and is upgraded to the many changes in the Mac 
world much faster than any other program. Now with the 
roundtable on Genie, Scott is in daily contact with his users. 
The most exciting thing for me, however, is what's lying up 
ahead. Scott has promised a high-res BBS version of Red 
Ryder Host and an accompanying version of Red Ryder. 
Later....Salty 

From: THE ATOM 

More on the Red Ryder debate... Red Ryder is ok, the 
ONLY reason I use it is because you don't have to open a 
document to get the settings, and you can switch from 1200- 
2400 baud without pulling down a menu.. on the minus 
side... the xmodem transfer is terrible! Before 8.0 I got maybe 
1 download out of 50 that worked. Now its up to 45 out of 50 
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but I've had it trash a couple of my disks completely, so that 
they give a system error when you stick them in! (no 
ejectinit at all).. The save off top option is really strange, 
and the text selection doesn't work too well either. What do 
I do now? I switched to Microfone. which if you haven't seen, 
look at it, its great!! The xmodem works perfect, tells you a 
lot more info during the transfer than red, and I've never had it 
o out to never-never land duringa transfer (fast too).. 

It also has Watch Me mode (I think it had it before RR 
not sure tho) that will make you a macro by just logging on 
to a BBS. AND its macro capabilites are incredible, almost 
like a languange with loops / if-then-else, repeat until, 
send/receive /wait for text..etc.. about 30 commands. And 
you can set up macros at the bottom of the screen as buttons, 
so you don't have to switch the "mode" at the top like red. 

But the thing I dislike most about RR, is that its window 
is fixed and you can't resize or move it. DA's are virtually 
useless since you can't have them open while on a system. 
And whenever Hertzefield releases his Multi-mac finder, 
you'll be able to see your other applications behind Microfone 
and select them, instead of using a switcher-like command 
key or menu choice ala the old Multimac (going from paint to 
finder). 

From: THE DUMACKER 

Okay, Okay 

RR9.0- ouch 

RR9.1- this came and went so fast I didn't see it. 

RR9.2- I have yet to have this thing blow out on me! 

The biggest problem I have seen with X-Modem on 9.2 
is using the "Supercharged" feature. I find this inoperable on 
Baudville and Macville. I see it as only being a slight 
problem in tim time timing! Oh yeah, it doesn't work on 


Genie either. 

System/Finder/Chooser Bugs 

From: TIM HEWITT 

Here are a few known bugs in the current release of 
System/Finder/Chooser [3.1.1]. These came from a techie at 
General Computer, and will soon be announced with fixes in 
an Apple release. 

#1) The Resource Manager in the 128k ROMs, has a 
problem with odd sized resources. Be very careful, as this 
bug can trash your system totally, and if you are running a 
hard drive -any brand- it may cause your hard drive to be 
unreadable. 

#2) Chooser does not call _UpdateResFile after you 
change your printer options. This means the new printer info 
is not written out to disk in some cases. Suggested fix- run 
chooser from within another app only. This will guarantee 
that the changes get written out when the application closes 
normally. 

#3) Finder 5.2 does not close and update open resources 
when exiting via Shut Down. This can cause corruption of 
the resouce map and leave the file unreadable. [Aldus just sent 
a postcard to registered owners saying 3.1.1 can trash 
Pagemaker Files. Could this be related? -Ed.] 

The latest unofficial word from Apple (I called about this) 
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is we may see System 3.2 released with the RM bugs fixed, 
and the rest of the bug chasing will continue into 3.3. If not 
there will be a fix (installer scripted) for problems, and a new 
Finder. It depends on a couple of other known bugs planned 
to be fixed in 3.2, being fixed. When 3.2 is released, a new 
Finder and Chooser will accompany it. If you know of any 
bugs in the ROMs, let them know at Tech Support and 
maybe we can get them fixed in this release. 

The New Mac 

TIM CELESKI 

Gee....it has been a while since we've had any rumors on 
a new Mac. I thought I'd pass this one on so we all can clear 
desk space for it. A friend is a developer for a Mac product 
that is highly dependent on the dimentions of the Mac Case. 
He has been talking to Apple recently and they gave him 
dimensions for the new Mac. Almost exactly the size of the 
Imagewriter L.. appoximately 16x12x5. That's the CPU box 
of course..Guess I'll have to remodel my MacTable 

I wish I had some great information about new 
coprocessors or terrific new architechture. We all know what it 
will probably have. And now I have seen an Apple supplied 
sample of the plastic to be used in the case of "Johnathon". It 
will be PLATINUM GREY....at least that is how Apple 
refers to it. Light in color, around the same density as the 
current Mac. Time to call the interior decorator and get rid of 
all this beige! 

External INIT resources 

From: BOB DENNY 

You can have an INIT resource that gets run during boot 
without putting it into the system file. Just put your private 
INITs into a file of type RDEV and put the file into the 
"blessed" folder on HFS (anywhere on boot volume for 
MFS). 

Parameter RAM & Debugging w/Symbols 

From: DON L 

The "Chooser" never seems to update parameter RAM. It 
only modifies the low memory copy at SysParam (20 bytes 
at $01F8). To force the update of parameter RAM you must 
change a setting in the "Control Panel". The control panel 
always seems to update parameter RAM immediately. 

Here's a tip for those of you who like the way the high 
level languages put symbol names in the code segment for 
the Mac debuggers to find, but want to get the same effect 
from assembly language. The debuggers are keyed to the 
LINK...UNLINK combination followed by a RTS or a JMP 
instruction. They look at the eight bytes following the RTS 
or the JMP and take them as the symbol name. The eight 
bytes should not contain any lower case characters. The 
following two examples show how to code this with and 
without parameters passed on the stack. 


label123: 
LINK A6,#-nnn 
UNLK A6 
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MOVEA.L(SP)+,A0 
ADDA #mmm,SP 


; return address 
; parameter byte count 


JMP (AO) 

DC.B 'LABEL 123' 
label456: 

LINK A6,#-nnn 

UNLK A6 

RTS 

DC.B ' LABEL456' 


From: CHIEF WIZARD 

Just as an added note on the previous post, the common 
method of storing the name after the routine has the high bit 
set on the first character only. Some debuggers rely on this, 
and some don't. Also, be sure to have EXACTLY eight 
characters. Pad with spaces if your name is shorter than 8. 

Softworks Business Basic 

DAVE KELLY 

Just got my copy of Softworks BUSINESS Basic (same 
as their PERSONAL Basic with ISAM file stuff added). 
Well, it does a terrible job with HFS, just like the 
PERSONAL Basic. You can still run it and get around all the 

incompatibility problems, but you've got to understand why 
it doesn't work. Hope they get their act together. 

I tried version 3.0 of ZBASIC and it was the pits. Looks 
like they have not worked out all the bugs. I typed ina 
couple of simple statements in the editor mode and returned 
to the command mode and... BOMB!!! Also it looks like 
they made too much effort in trying to keep their BASIC 
compatible with other machines. Most serious programmers 
will use the toolbox for most applications anyway (Toolbox 
commands are not transportable from one machine to 
another). They told me last week that version 3.2 was soon to 
be released. Hope they fix it. They said they haven't sent 
any copies to MacUser, MacWorld, Macazine, NibbleMac or 
myself (MacTutor). I wouldn't send out my unfinished 
product to them either. [That's interesting because they sent 
me a copy of 3.01 so they must think it's ready for review. - 
Ed.] Dave 

Mac vs Amiga 

From: FRANK HENRIQUEZ 

I got my Amiga a couple of months ago, so I guess that 
means I'm an "expert" on the pros and cons of the Mac and 
the Amiga. In terms of hardware, the Amiga is really 
wonderful; great graphics (in color, if you're into color...) 
stereo sound, nice high powered  co-processor chips to do all 
the dirty housekeeping for the CPU and a true expansion slot 
(not to mention serial and parallel ports and 3 video 
outputs...) The Mac is a swell little machine, and a true 
Work of art, in terms of design, but it's quite limited in terms 
of hardware. (You're probably thinking I've been brainwashed 
by Commodore Software. Ah yes... THAT. 

The Mac wins hands down on this one, and in a big way. 
I have yet to see an Amiga program that can compare in 
quality to an equivalent Mac program. 
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In part, this is due to the truly moronic and amateurish 
operating system and development tools (the OS is refered to 
as "AmigaDOG") good ol' Finder 1.1 would be an 
improvement over it's Amiga equivalent, the Workbench. A 
good deal of the problem lies in the details; the Amiga lacks a 
standard user interface, like the Mac's and what there is in 
terms of standards is at a very low level. The Amiga has a 
long way to go to catch up with the Mac...at least in 
software. 

Lightspeed C 

From: BOB DENNY 

I have been using Lightspeed C for the past month or so. 
Its really a delight to use. However, those of you 
contemplating the switch should be aware of the following: 

(1) ints default to 16 bits. Like Lisa Pascal, but a pain 
when converting applications written in other Mac C's. Bogus 
assumption for 68020 with 32-bit "bus". I almost think it's 
bogus in any case, since the "natural" word size is 32-bits. 

(2) There is a 400+ byte "preamble" (CODE-1) of code 
on the front of ANYTHING that Lightspeed makes ... drivers, 
DA's, CODE resources... as well as apps. This makes it 
useless for FKEY's, INIT resources and many driver 
applications. The preamble contains code blocks for handling 
switch statements, long multiplies & divides and some other 
language ops that they implemented in threaded code. 

(3) CODE resources cannot use static data (ref'd off of AS 
or A4), but Lightspeed won't even compile such code. Why 
not let "us" handle global area setup and A4/AS setup in 
ASM? Did that in Consulair; can't do it in Lightspeed. 

(4) RelConv won't deal with "resource" code. So you 
can't link things like PROC resources, etc. 

Despite the preceding, I use Lightspeed for almost 
everything. What I can't do in Lightspeed I just do in MDS 
assembler/linker. It's really wonderful with TMON, which 
shows the routine name & other symbols because the 
Lightspeed linker can put symbol info into executable image 
like the Lisa linker. AW-REET! 

To use LightSpeed with stuff not in the MacTraps 
library, you can do the following undocumented trick: 

pascal void foo() = 0xA123; 

This declares a function foo with void return to be a 
toolbox trap A123. The "void" can be replaced by come other 
type of function return type. The function can be called with 
an arbitrary number of args. This sweet little extension 
allowed me to write an H file for the list manager and 
completely avoid glue routines. The only bad part (and I 
don't give a damn) is that the compiler doesn't type check the 
args. AWWWW.... 

Now if they just hadn't defined INTs to be 16 bits ... 

TRUE BASIC RELEASED 

DAVE SMITH 

Addison-Wesley has released true Basic for the Mac and 
this baby looks great! My favorite benchmark runs in 0.95 sec 
which makes it faster than an HP 9836! And it has matrix 
operations including inverse. In fact the Basic looks 
very much like HP Basic with blocked If 
Then Else constructs. More next month! 


SE 
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Mousehole Report 


This month its MouseFest time again. We'll be at the 
Anaheim Mac MacFest show having a great time as usual. 
Southern California is a hotbed of Mac activity, so we're 
expecting a great show. Maybe we'll see you there! 

If you are interested in getting on the ‘Hole, drop us a 
SASE at Post Office Box 2323, Orange, CA 92669. Even if 
you don't have a modem but want to share some gossip or ask 
a question, write to us. We will pass on the most interesting 
questions to the rest of the MouseHolers. Until next time- 
Rusty. 

Mac + Woes 
DAVE MORRIS 

I have a couple of problems with programs on the new 
ROMS. I use EDIT 2.0 to read my massive downloads from 
RR. EDIT has real problems with cut and paste with the new 
ROMS. I would use QUED etc. except that they all run with 
32K text max. Know of any other text editors that work with 
large text files? Also, does anyone have the patches to 
MazeWars to allow it to run on the Mac+? Thanks much, 
and glad to hear you are back up. I missed my weekly 
MouseHole fix. 

MazeWars 
MACOWACO 

MazeWars is no longer an Apple freebie (it never really 
was); in fact it is no longer in the tech library up there. I've 
been told that the guys that wrote it are going to sell it along 
with a bunch of other Appletalk games. Oh Boy, I can't wait 
to shoot my Supervisor right in the eyeball! Did anybody 
catch the color Mac at the beginning of Short Circuit? I would 
bet that it was actually a kludge for the film. That is, they 
wanted the graphic of the robot arm in color and Apple had 
paid big bucks for exposure of the Mac so someone stuck a 
fake CRT into a dummy Mac body. Only guessing of course. 
I doubt the color Mac will look like that. 


Stupid HFS Bug of the Week Club 
TOOTHY MACS 
Have any of you tried doing a 'set Startup to an 
application that sits on the desktop? The "final" version of 
finder (5.3) and system (3.2) only finds the path when the 
application is in a folder! Try it. 


LaserWriter Trick 
BOB DENNY 

Those of you who have more than one Mac hooked to a 
Laser ... 

The first one to use it after it's powered up loads the 
“Laser Prep", and if it happens to be an "older" version, 
everyone else with current drivers is locked out of printing. It 
tells you to turn the printer off and on. I hate doing that. I 
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IOS MouseHole === 


Rusty Hodge 

MacTutor Contributing Editor 
Mousehole BBS 

P.O. Box 2323 

Orange, CA 92669 


loathe things without a reset button. 

So use your LW Download program to send the 
following PostScript program to the Laser. It resets the 
printer without power-cycling: 

systemdict begin exit 

That's it! 


Unprotecting Basic 
CLEM SNIDE 

Want to unprotect a MS Basic program? If you call the 
download section, there's a text file called Basic Unprotect by 
the Ant Killer. It'S very simple and straight forward. [Note: A 
far easier approach is to run our unprotect program we 
published in last month's MacTutor. It automatically finds and 
unprotects the program in memory. -Ed.] 

All you need is a Memory Disassembler DA that can also 
be found in the downloads. 

Simply put, what you need to do is insert at the 
beginning of your program a number telling basic the length 
of the first line so that the interpreter can list it. 

You open Basic, then open your protected program 
(w/out running it), then you choose new from the menu. What 
this does is reset (in memory) the line counters to 00 00. So 
using your DA you search through memory, find the 
beginning of your program, count the bits between the 00 00 
markers, then poke it to the first 00 00, save the program, 
then open it and save it again. 

Anyway...download the file, it is easy and straight 
forward and could save your life sometime. 


The story of System 3.2 
JACK KOBZEFF 

The reasons behind the two releases of Finder 5 .3-System 
3.2... On Monday (couple of weeks ago) the System was 
‘frozen’ and released. 

The next day, an Apple employee was using 'Localizer' to 
change some resources for a foreign version. After the change, 
he/she discovered that there were still some resources that 
hadn't been altered. To make a long story short, they soon 
discovered that there were many resources duplicated in the 
System. About 20% by volume. The second release removes 
the duplicates. I guess that everybody at Apple uses hard disks, 
and wouldn't notice an extra 40-60k. 


Micah AT20 
LARRY DZSKI 
Being one of the luck few to get one of the first ever 
AT20's, I can tell you it IS superior to a HyperDrive, not only 
in speed, (it's at least a factor of 2 faster in some cases), but 
the reliability of the Micah Drive is far, far, better than Hyper. 
I travel with my Mac almost constantly, and the ability to 
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‘take a lickin and keep on tickin' (sorry Timex) is important to 
me. I had no less than 3 Hyper 20's fail on me on business 
trips, once in the middle of an important presentation. The 
Micah has been on no less than 7 trips with me, all by air, 
and it still hasn't skipped a bit. I recommend them highly. 
Good product, great support, and good software. 


Lisp, SmallTalk-80, etc... 
Micro Ghoul 

Some time ago a question was posed as to whether or not 
you can use SmallTalk-80 for the Macintosh on the Mac +. I 
am presently using it on the Mac + with an HD 20. Though I 
have found some unusual features in the package, for $50 
dollars you can not really go that off! The key to making 
SmallTalk-80 work is having the memory, disk space, and 
reading their docs! Now, for the first time (well, sort of), you 
are able to use SmallTalk-80 on your Mac (not just your Mac 
XL)! Ihighly recommend the package as a cost effective way 
to get into the object oriented programming environment! 

Seriously there are about three people up at Apple that I 
have spoken to you with some consistency and they are really 
excited about their product and getting the public involved. 
They are trying to get a newsletter going, anyone want to get 
involved with that? To end a very dull paragraph, SmallTalk- 
80 is an enjoyable, productive environment to create working 
protos or models of problems that the software community 
faces today. 

On that note, has anyone heard anything about a rumor 
that PPI (of Objective C fame) is coming out for a version for 
the Mac? I use their C for the Sun 3 and love it! If anyone 
knows anything please contact me, as right now I am forced to 
go to work at all hours of the day, night, weekends to 
accomplish tasks that could be modeled on the Mac! 

I recently got the new version of ExperLisp 
(MACOWACO shudders!) version 1.5 w/ speech & compiler. 
Believe it or not I have not had a great deal of trouble with the 
product! It is not copy protected, though they did make it so 
that any registered owner would have to be nuts to give it out! 
It does not produce stand alone code, but it does allow saving 
of compiled code. The only thing that I have done with it do 
far is create a model of a LMI Lambda communicating via 
TCP/IP with a VAX running SIMSCRIPT II.5, but it did not 
bomb once! I did note the fact that several of the routines 
needed to be modified to work on the LMI (needless to say I 
doubt ExperTelligence is at fault there!), but I was able to 
create a a workable presentation for demonstrating the interface 
that we are creating without having to waste too much time 
on the VAX or LMI. Is it worth it now? Well, sort of. I 
will speak about ExperTelligence newest product ExperProlog 
// when I have had more time to play with it. On a first 
glance it too, was not that bad! 


Infosphere 
MACOWACO 
I finally got a return call for my troubles with MacServe 
(lots of random bombs). 
The only thing the tech guy could tell me was to use 
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ONLY MacServe volumes and minimize HFS volumes. 
Create a dummy two meg volume for system dynamics then 
build the volumes for other stuff. When done remove the 
dummy volume. 

This gives a good amount of contiguous disk space for 
the system. I told him I want to use the HFS folders for 
nonserver stuff and he told me I'd get better performance if I 
did them all with MacServe. 

Needless to say that would be a definite step backward, I 
told him so and he says that... "so little has been documented 
about HFS that there is no way of knowing to what degree the 
HD is fragmented." I ask you guys...is this so or what? 


400K HFS Finder 5.2 
LASER DOLPHIN 

Finder 5.2 normally makes 400K disks MFS (non- 
hierarchical) volumes. 

Even if you have formatted a 400K disk with the Option 
key down, thereby making it an HFS volume, when you copy 
that volume in its entirety onto another 400K disk, the target 
disk is a flat volume with "little pretend folders" instead of 
true subdirectories. 

An undocumented feature of Finder 5.2 is that, if you 
hold down Option when copying one 400K disk to another (by 
dragging the disk icon onto the other disk icon), the target 
volume will become an HFS volume, regardless of whether it 
was formatted that way in the first place. 


System/Finder/Chooser Bugs 
TIM HEWITT 

Here are a few known bugs in the current release of 
System/Finder/Chooser (3.1.1, 5.2). These came from a 
techie at General Computer, and will soon be announced with 
fixes in an Apple release (3.2, 5.3). 

1) The Resource Manager in the 128k ROMS, has a 
problem with odd sized resources. Be very careful, as this 
bug can trash your system totally, and if you are running a 
hard drive -any brand- it may cause your hard drive to be 
unreadable. 

2) Chooser does not call _UpdateResFile after you change 
your printer options. This means the new printer info is not 
written out to disk in some cases. Suggested fix— run chooser 
from within another app only. This will guarantee that the 
changes get written out when the application closes normally. 

3) Finder 5.2 does not close and update open resources 
when exiting via Shut Down. This can cause corruption of 
the resource map and leave the file unreadable. 

The latest unofficial word from Apple (I called about this) 
is we may see System 3.2 released with the RM bugs fixed, 
and the rest of the bug chasing will continue into 3.3. If not 
there will be a fix (installer scripted) for problems, and a new 
Finder. It depends on a couple of other known bugs planned 
to be fixed in 3.2, being fixed. When 3.2 is released, a new 
Finder and Chooser will accompany it. If you know of any 
bugs in the ROMS, let them know at Tech Support and 


maybe we can get them fixed in this release. 
EEE 
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Mousehole Report 


Applications to the mousehole must include a SASE. 


Anaheim Expo A Mixed Success! 
Rusty Hodge 

The Anaheim MacExpo was moderately small, but that is 
because it was only two weeks before the giant Boston Mac 
Show. However, it did seem to have a lot of smaller 
developers there that might have been lost at a bigger show. 
Some of my favorites were Mac WeedMan (Nova Electronics 
& Software, Riverside, CA), an “advanced lawn care 
management program" , Parameter Manager (SMS Inc., San 
Jose, CA), a system for analyzing technical data and 
DataSpace's Laser Server (Ontario, Canada). The Laser Server 
is a multi-user Appletalk print server, or a 2 megabyte printer 
buffer if you must, but a real time saver for those who spend 
their time in que for the LaserWriter. If the price is too high, 
Mac America had a software Laser spooler that does the same 
thing for only $99! And I almost forgot, what promises to be 
the new standard in word processing, HabaWord. Imagine more 
power than Microsoft Word but easier to use than MacWrite. 
Imagine multiple on-screen columns. Thanks to Vision 
Technologies (1-800-MAC-DISK) for demonstrating it. 

Of course our PizzaFest was most fun of all. As always 
we ran out out of power outlets, but Jim Reekes described it 
best: "Where's the power outlets"? 
(chomp...chomp...munch...slurp.) "Could you gimme another 
piece of that one with the olives?" ( ...Chomp...chomp.) 
"Anyone got another Appletalk connector"?... [moments 
later]... "Yer Jim Reekes,...really? I expected you to look like 
some....hey, where'd ya get that shirt"?" 

Jim was wearing this incredible shirt covered with 
computers of all sorts, including a Lisa with the old twiggy 
drives. I got slaughtered at Maze Wars as always and there 
was a curious crowd of Disneyland tourists watching us play 
for the longest time! (The pizza parlor was a block down the 
street from Disneyland). Now, can we do it again in Boston? 
[Just give the word Rusty...-Ed] 

Thanks where thanks is due: Michael Sackett's Cleanup 
program is indespensible when it comes to putting this 
column together. Cleanup lets you take four "target strings" 
in a file and replace them with something else, including both 
printable and control characters. Thanks Michael! Want a 
password to the Mousehole? Write to us at the address shown 
above in our article header with enclosed SASE. 

400k disks 
THE ATOM 

I've got a Mac+ with an external 800k drive, running HFS 
and I've been trying to initialize a 400k disk that has at least 
394k free. No matter how I format it I can't get it to give me 
more than 387K free! The disk doesn't need to be HFS, I just 
need 394k. does anyone know how I can get a disk with that 
much free? What happens to the other 13k anyway? 
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Rusty Hodge 

MacTutor Contributing Editor 
Mousehole BBS 

P.O. Box 2323 

Orange, CA 92669 


MAC SCOTTY 

In the old days before HFS, Apple had a K = 1000 bytes. 
With the advent of HFS they decided to do things the old 
fashioned way (the correct way) and make a K = 1024 bytes. 
This means that the disk still holds the same amount of 
information and reports the K correctly! 

Hard Disk Backup 
RICK SCHERLE 

I haven't tried this on non-Apple drives, but I have used a 
GREAT backup program on the HD20. It is called 
MegaCopy from Dantz Software Development in Berkeley. 
MegaCopy supports date/time, FileType, and individual file 
selection, splits files across volumes, verifies after writing, 
uses a fast buffering system, etc., etċ. And, because it uses 
the file system correctly, should work on any "standard" drive. 

One problem, it works ONLY ON MAC+. No, this is not 
an ad. It's just a great program. 
System 3.2, Finder 5.3, Hyperdrive20 and 
lots of problems 
The Anarchist 

I have a Hyper 20 in my Mac+. I am running the new 3.2 
System, etc, and the other day, a friend came over with his 
SCSI hard disk to transfer some "new warez" onto my hyper. 
I run HFS in one single drawer and have had no problems 
except after he leaves, the boot blocks seem to get written 
over or something. I can transfer system and finder off the 
floppy back onto the hyper and it works for 3 or 4 more 
boots, then crashes again. The only solution is to reformat 
the drive and restore all the files. Is this a System 3.2 bug 
with SCSI? Is my Hyper a piece of poop? (I like it..) Help! 

JIM REEKES 

"Don't make the startup drawer HFS. Keep it a MFS 
drawer. The rest of them can be HFS. You should make a 
minimal startup drawer. Then make the rest of the space 
whatever you want." 

800K MFS Disks 
DAVE KELLY 

If you want 800K MFS disks all you have to do is take 
any initialized 800K disk and erase it with an old version of 
finder (i.e. version 4.1). It seems to works just fine and so do 
those programs that don't yet support HFS. 

Warp Nine Drives 
R. L. Sandefur (MouseHole Mailbox) 

While I have no doubt that ISOEMAC experienced the 
problems reported in the May 1986 MacTutor MouseHole 
Report, my experience with Warp 9 in both their support and 
business practices has been entirely satisfactory. I ordered my 
hard disk (Warp 20) on 04-May 86; it was promised by 11- 
May 86. I felt the instructions for installing the Warp 20 
were a bit terse for putting a $900 piece of equipment in a 
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$3,000 computer but when I called Warp 9, the talked me 
right through the unclear parts. In using the Warp 20 (v1.6.1) 
with the Manx 1.06g Shell and MS Fortran 2.1 and the MFS 
(as opposed to HFS) and new ROMs in a 512K Mac, I had no 
problems. If I have a system crash due to applications I am 
developing, I reboot and reinstall the SCSI disk using the 3.5 
inch diskette provided by Warp 9. One concern under the 
MFS which could be a problem under the HFS is that the 
Warp 20 MFS allocates files in 35K blocks.Warp 9 provides 
the least expensive 20 Meg internal hard disk for the Mac (as 
far as I know). If ISOEMAC's experience with Warp 9 an 
isolated event it would a shame if they got a bad reputation. 
TOM SHERMAN 

Bought my Warp Nine 20 Meg SCSI last week and was 
pleased for a day. Had been waiting for a hard drive since Feb 
'84! Have lost maybe 10 files since then, have had to 
reformat and am not knocked out by the speed. DiskBench3 
came back with numbers around 3700 with access time=263. 
Thought I was getting a bargain until I called SuperMac 
Technologies and found that their new developer's price was 
$695! And next month they'll be giving out a free backup 
program... Guess I'll be taking advantage of Warp Nine's 30 
day money back... Anyone have experience with SuperMac's 
20meg drive??? 

Micah AT20 
THE PSUEDOHACKER 

I previously asked if anyone had a Micah AT20 internal 
drive. Only one of you guys responded. Having various 
connections, I was able to get the drive at near dealer cost. 
This drive is just like a Hyper. The speed is practically 
identical. It's quiet, uses an internal fan, and it's own SCSI 
port. Fully HFS compatible!! Apple's ROMs, variable 
partitions, etc. I love it. I've been putting it through the mill 
and absolutely no complaints. I recommend the drive 
wholeheartedly. 

TML 1.1 bug w/MFS? 
ED DEMEULLE 

Does anyone here know of a bug in TML Pascal v1.1 
w/MFS? Here are the symptoms: same source file, same 
compiler and linker, same disks...... two different applications 
created. Both show the same size per get info at the finder 
but, in the heap, the one on HFS has a code segment size of 
1BEA and the one on MFS is only 38C in size (per TMON). 
Sounds like the problem lies in the linker. What tipped me 
(actually, me and Don) was that the one on MFS didn't work 
properly w/ command keys. So I go over to Don's and 
recompile it and it worked (thought I was ready for a nice 
padded cell at this point). Take the disks home, rename the 
application created at Don's and try again. Still didn't work. 
Does anyone one have any insight into this or is this 
REALLY weird? 

More great tech tips 
JIM REEKES 

Whilst in the mini-monitor, type "G 40F6D8" and exit to 
the Finder. (ROM address of _ExitToShell for you 
programmer heads) Hidden feature for ImageWriter //s and 
the driver version 2.3. You can select between bi-directional 
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and non bi-directional printing by (are you ready for this 
one).... Choose Print from the file menu, don't click on OK 
yet. First hold down the "Option-Shift-Cap Locks" keys, 
then click on OK. Now you'll forever be printing in bi- 
directional mode. To select single directional print again, 
choose Print, then hold down the "Command-Option-Shift- 
Caps Lock" keys and click OK. This must be a soft-switch 
in the ImageWriter drivers. Because it retains this setting 
until you select the other mode. 
Also, "Set Startup" only works if an application is in the 
blessed folder. 
Bi-direct print 
MACOWACO 
The bi-directional prinüng in standard mode on a 
Imagewriter ll is faster, but, not ideal. After printing from 
draw I can understand why Apple has not been overly anxious 
to tell all users about this obscurely documented feature. 
Vertical lines look weird, and sometimes text looks weird too. 
Also it don't work in paint-like printing (read that as 
MacPaint, Fullpaint, Comicworks Paint cutter, etc.). It ain't 
easy to line those little bitty dots up across lines! 
SmallTalk-80 
BOB DENNY 
Alan Wootton screwed me for my 40th birthday (yup ...). 
He gave me a copy of SmallTalk-80. I have been sorta 
interested for a while. Well, it's pretty terrific. A great 
workout for us old stodgy programmers with silver threads 
amongst the missing. Anyone else got into it yet? As a side 
issue, I build a "PAP" device driver that allows you to do 
normal "PB" calls to send PostScript to the LaserWriter. (See 
this issue of MacTutor). Anyway, I've added laser printing to 
the SmallTalk-80 system (PAP driver & fileIn goodie). I was 
up at Apple today & was surprised to find out that they hadn't 
done a LaserWriter package for SmallTalk-80! So I gave them 
mine & they said it will probably be included with the next 
release. Enough bragging, anyone interested in SmallTalk-80? 
I feel like a real junior birdman, but I LOVE it. 
Frozen Folder 
THE TOOLSMITH 
I just downloaded a demo reminder program and have run 
across some VERY disturbing behavior. I ran it once to see 
what it did, DIDN'T install it, and forgot about it for a while. 
This morning, when I went to open my downloads folder, the 
mouse froze the second the window started drawing. Had to 
reboot, tried this several times, same thing each time. Deleted 
the offender using Developers Tools DA, rebooted and the 1st 
time, I was OK - however, it went back to it's evil ways after 
that. Replaced the system file. Duplicated the folder, tried to 
trash the original - no luck, busy/locked files it said. Went 
thru and deleted everything I could (certain folders that hadn't 
been touched in weeks were Locked, it said). Finally got rid 
of the original, but the duplicate folder is just as frozen. 
Opening the folder freezes the mouse - period. I'm using 
system 3.2 with Finder 5.3 straight from Apple - no funny 
FKEYs or anything Does anybody have any idea what the 
heck's going on? I don't get the feeling that the reminder 
program is consciously a Trojan horse, but it could be very 


© The Complete MacTutor, Vol. 2 


dangerous, it seems. All help will be greatly appreciated. 
HFS fragmentation 
JIM REEKES 
Wow. I have been using the Apple HD20 now for a few 
months, (I like it) It is storing about 550 files or 15mb. I 
am real careful about fragmenting the disk, and about every 
other month I format a fresh drive and install all my files on 
the new HD20. (Good thing I work at a dealership) Out of 
curiosity I wanted to find out how fragmented the old drive 
may have become. According to FEdit+ the old drive had a 
Fragmentation Index of 0.11 whatever that means. 
Sometimes it got a high as 0.15. Anyway, on the fresh disk 
the index was 0.00. Hurray. I check the drives with Get Info 
from the Finder and the new drive has an extra 300k of space. 
Hmmmm. By Finder copying all the files from one HD20 
with 15mb to another blank HD20, I gained 300k of storage! 
Nope, this had nothing to do with the DeskTop file. I wiped 
it out before testing. The moral is, Initialize your HFS hard 
drives on a regular basis. This will also speed up the drive 
access time. 
SuperMac DataFrame 
TOM SHERMAN 
Just received DataFrame from SuperMac and am quite 
pleased. ($695 developer price is nice too!). Disk bench3 
gave numbers of 2138/2113 read/write and access of 534. My 
Warp nine (which is going back tomorrow) was 3727/3742 
and 251. The Warp Nine kept losing files (Sorry, that file 
had to be skipped!@*#) and was quite noisy. The DataFrame 
seems faster but also suffers from a soft squeeking noise. 
Hmmmm. Anyway, it is HEAVEN to finally have a hard 
disk! Let's here it for 400K of fonts and 15 desk accessories!! 
RAMsafe & Hard Drives 
ISOEMAC 
When using Servant .75 and RAMsafe I have found that 
when you use the shutdown feature from Servant the 
supposed Non-volatile RAMsafe becomes volatile! Servant's 
shutdown clears RAM even with RAMsafe. The only 
company that had anything excitingly new at Anaheim 
MacExpo was Peak Systems. They introduced a 65MB hard 
disk that features an advertised 23 millisecond access time and 
a list price of 2495.00! A friend of mine was so impressed he 
purchased one on the spot We ran DiskBench 3.0 and 
received access times of 122 and 136. As far as I know this is 
the fastest Mac Hard Disk currently available. The Peak 
drives also come with a 1 year warranty. 
No Startup Screens 
JACK KOBZEFF 
I've had a couple of friends tell me that they've had some 
wierd things happen with the new system software and 
Startup Screens. Now I hear that Apple does not recommend 
using Startup Screens with System 3.2, and may remove the 
capability for them in future Systems. Too bad, I thought it 
was one of little things that made the Mac 'personal'. 
New Products 
MIKE STEINER 
Re: "Apple will be introducing more new products in the 
next twelve months than in the past nine years." Scully said 
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the same thing on the CompuServe conference. Are they 
including minor items like joysticks and interface cards? 
Best I can tell, not counting minor items, Apple introduced 
about 12 major products in 9 years (Apple I, Apple II, II+, 
lle, Ilc, Mac, Mac Plus, Apple ///, Lisa, LaserWriter, DMP, 
Imagewriter, IW II, (There's 13 already) Scribe, three 
modems, five monitors) When you  deduct the non-major 
items from that list, you are left with about a dozen. 

Prediction: New products will be announced on Sept. 15th. 
Rationale: the rebate program for the // series ends on Sat, 
Sept. 13th. 

Apple 16bitter 
FRANK HENRIQUEZ 

The new 16 bit Apple // is based on the 65xxx (forgot the 
last three digits) a bastardized version of the 6502. 
Internally, it looks like a souped up 6809 with fancy 
instruction and bank select registers. It certainly isn't as nice 
as a 68000, but it'll make a neat upgrade for the Apple 6502 
family. 68020 are the way to go for high powered machines. 
Motorola is really aiming at dropping the price of the 68020 
and 68881, and they've just released a 20MHZ version of the 
68020. There are rumors that they're working on the 
68040...which is basically a super pipelined 68020 (with a 
separate data bus for the instruction cache). Ina year or so, 
it'll probably be cheaper (more bangs/buck) to design a 
computer with a 68020 than with a 68010 or 68000. Forget 
Intel; it's actually kinda sad that they've based all their 
"modern" CPU's on the old 8008. (The 80287 is to some 
degree compatible with the 8008. Wow. Lots of Mark-8 
software out there...I've heard there's a great teletype driver on 
paper tape available for the 8008.) 

Megascreen 
TIM CELESKI 

Had a chance to see the MegaScreen at the Business 
Forum. Very nice indeed. 19" 1,000x900 monitor that lets 
you get a full size pagemaker document up at full size. The 
price is a little hard to swallow with all the competition 
coming up. Had a talk with a developer who is working with 
some of the other monitor makers, says that Burrell Smith's 
new monitor is a verticle and will be very competitive in 
pricing. Almost forgot to mention the price........ Megascreen 
is $2,995. Awfully nice!!! 

The Corsair 
Faster SetlText Operation? 

I have a dialog that has about 80 static text fields in 
them.The data is all 3-5 characters long and my problem is 
that it is incredibly slow. It takes almost 5 seconds to print to 
80 fields. I am using SetIText(itemHandle,string); what I need 
is some kind of alternative to this. I am convinced that it is 
the rom call that is causing the speed problem. 

The way I solved the problem (just in case anyone was 
wondering) is I stored the rectangles that get returned when I 
call GetDItem into an array that is indexed the same way my 
static text fields are; then to print text to the field, I do an 
EraseRect, a MoveTo and a DrawString based on which 
rectangle/field is indexed. It turned out to be about 4000 tim 
faster (literally). Pad! 
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Mousehole Report 
More on Hard disks & Jonathan 


To join, send SASE to Rusty Hodge 


More On Hard Disks 
Rusty Hodge, Sys Op 

The battle of the hard disks continues. A few of the 
newer players are the ProApp 20, the Easy Drive, the 
HyperDrive FX-20 and a few others I'm forgetting to mention. 
So what is so special about these drives? 

The ProAPP will work on a SCSI port, or on a 512 
through the disk port, or on an Apple //e or //c. You can 
partition the drive between Apple // and Mac, even use them 
simultaneously to a limited extent (if one is accessing the 
drive while the other tried, you'll get a nasty I/O error). They 
tell me it's not supposed to work that way, but it does. 
Speedwise, the ProAPP seems about as fast as the Dataframe, 
although the particular unit I have is a bit noisier. 

. The Easy Drive is the true mass storage winner. About 
as pretty as a LoDown (read: plain), but you can't beat 45mb 
for $1500 and 60mb for a couple hundred more. Can't say 
more because I only played with one briefly but hope to have 
one by next month (hint hint...). 

Last, but we hope not least is the HyperDrive FX-20, 
General Computer's first entry into the SCSI market. Novel 
features include keeping the SCSI parameters in the drive's 
own parameter RAM, therefore allowing you to graphically 
set it up on the SCSI chain. It also comes with most of the 
traditional Hyper goodies including the backup and security 
programs, however no Drawers and no HyperNet! It is also 
big, boxy and ugly... but then who am I to say? (Sull, a lot 
of people think the IBM PC is a great looking box...) 

Tecmar 
BEAKER 

Did everyone know what happened to Tecmar? They 
were having some financial problems, but someone thought 
they'd be a good investment, so Tecmar got bought (believe it 
or not, Tecmar was privately held). 

Anyway, three weeks ago, about 110 people were laid 
off, around 1/5 of the employees. The guy I report to is still 
there. We talked about their new product, but I can't say. I 
did get some information that MacDrive owners should be 
interested in. To print with the MacDrive, you need to use the 
Imagewriter driver that was supplied on the MacDrive 2.2 
boot disk. Yes, this sucks. This means that if you have an 
Imagewriter II, you can't use any of its wonderful features. 
Sorry. Everything else in the 3.2 System works. 

He told me that there WILL be a new version of the 
MacDrive software, version 2.3. It'll have some neat stuff 
and will fix the Imagewriter problem. One other thing. 
HFS works fine on a MacDrive, just make a single ten-meg 
volume. The Volume Manager doesn't know about HFS, so 
it'll say "This volume has not been initialized" but fear not. 
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You can still mount the volume, and set it to be the startup 
volume. The only problem is that the System file needs to be 
in the Root. This in turn means that ALL system files need 
to be in the root, because the "System Folder" is only magic 
if it actually contains the System file. 
RUSTY HODGE 

There is a way to make the Tecmar run HFS and still 
keep the system stuff in the system folder. How do I know? 
I've got one doing that. I think it is because I'm using the HD- 
20 startup file. The 128k ROMS should do the same thing 
according to The Anarchist, but we haven't been able to try 
this. 

New Book 
MACOWACO 

A new book is on the shelves by the same company that 
produced Chernicoffs stuff called Object Oriented 
Programming on the Macintosh, by Kurt Schmucker. A quick 
scan showed a ton on MacApp. It's been over a year and a half 
since I spoke to Tesler about MacApp. There's a book on it, 
lots of press, but no MacApp! Reminds me of MacBASIC! 
[Note: Kurt Schmucker is doing a special issue in MacTutor 
on MacApp. Watch for it shortly. -Ed.] RE: the Object 
oriented programming course at NB. A bunch of us went to 
hear Mike Miller talk about development over a year ago, and 
he preached ExperLisp.. well? He also told us the 
LaserWriter will never be a major product... He also told us 
that C is a terrible language and nothing significant will ever 
be produced with it on the Mac...... Yawn. 

Hard Disks at the Mac Expo 
JACK KOBZEFF 
One thing that I noticed at the show. Almost everyone 


. who was not promoting one brand of hard disk or another (in 


other words, who got to choose which hard disk to use) was 
using the DataFrame 20. There were a couple of exceptions, 
but the vast majority were SuperMac DataFrames. I think 
that this indicates something - what, Im not sure. 
[Remember the first MacWorld Expo, where there were 
Corvus Omnidrives everywhere? Déja Vu? -Rusty] 

[Don't say that, Rusty, I just bought two Data Frames! 
Ouch. -Ed.] 

AST complaints 
JIM REEKES 

I've been fooling around with the AST 2000 and 4000 
and don't like it. First of all, it is VERY expensive. What 
do you get for the money? A hard disk system with integral 
tape back-up device. OK fine, it better knock my socks off. 
How does it work? Well, with the 4000 I want the ability to 
select a folder and backup everything in it. Sorry, no can do. 
Promised, but not ready. Oh well, how about a complete 
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volume back up? Well, you can only back up 60mb, not the 
complete volume. How fast is it? I wish I could tell you 
this, but after waiting for a hour I gave up and rebooted. AST 
said, "You need the lastest version, it's faster and available on 
our BBS". OK, fine. Called them, downloaded the stuff, and 
installed it. Here we go again. "Complete (well almost a 
complete) Volume Backup". This time I rebooted after 30 
minutes, never did get a backup. And another thing, what 
about the last 13 or so megabytes? Does it just get ignored, 
or can you back it up? The AST 2000 is a 20mb drive with 
a mini-tape drive. The tape device in the 2000 seems real 
bogus to me. Loud and slow. My biggest complaint against 
it is that you have to "Format the tape"! Why do you need to 
format tape? The format procedure takes over a hour; it 
doesn't come formatted from the factory. The first 2000 failed 
to format the tape. OK fine. "What's the problem?" I asked 
AST. They said I probably have a bad tape, try another one. I 
had been using the tape they supplied with the drive. The 
second tape failed, too. Two out of two, and no backup yet. 
Has anyone successfully backed up an AST? How many 
minutes per megabyte did it take? Our entire accounting 
software is stored on two 22mb drives. Including the time it 
takes to load in a fresh "unformatted" tape and push a button, 
we can back up 40mb in under five minutes. What is AST's 
problem? I like the speed of their 4000, but without a 
complete backup device, forget it. 
AST Drives 

GARY VOTH 
The main reason you have to format the tape drive is that 
AST configures it as an on-line volume; that is, it comes up 
in the Finder with its icon and behaves like an HFS disk. 
To do a backup, you simply do a Finder select-and-drag to 
move folders and files onto the tape. Their low-level device 
handlers are supposed do the rest. I know the thing works, 
since I saw one up and running at the Apple Business Forum 
in Long Beach. The price, however, seems a bit steep. AST, 
like Iomega Corp., is a big player in the corporate MIS 
market. I would recommend their products to a large buyer, 
but steer the individual user to something less expensive. 
My recommendation for a SCSI device at this moment is the 
DataFrame 20 by SuperMac. It's fast and reliable. The only 
person I know who had a problem with one called the 
company and they shipped a replacement to him before they 
received his defective unit in retum! There is no reason, with 
a SCSI interface, to have the tape backup unit integral with 
the hard disk. I would wait for a SCSI tape backup device 
from a respectable manufacturer and purchase it separately. 
The other way to go for business buyers is with the Apple 
HD20 and a sizeable RAM cache. Speed differences are 
minimal if they have enough memory to work with. 
Contrary to general belief, the RAM cache is very reliable 
with System 3.2/Finder 5.3. I routinely run a 256K cache 
along with Switcher as my normal "shell. The Finder gets 
loaded into slot 1 at boot time, and I rarely have to leave it. 

Of course, I have a Levco 2M board... 

AST drives 
VIDEO WHIZ 
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The tapes DO come formatted from the factory. The tape 
you describe sounds like it: 1) has an adjustment problem that 
came out because 3M changed their media and didn't bother to 
tell anyone about it, therefore requiring that all the tape drives 
in existing AST-2000s be readjusted, or 2) the power supply 
is out of adjustment. The second cause is very rare, but I 
won't say that shipping something has NEVER caused a 
problem. If anyone has any questions about AST's Apple 
products, feel free to call me at (714) 553-0340. That is 
AST's direct line to their Apple products group. Ask for Jim 
in Tech Support. 

Zenomorph 
OPEN MACINTOSH 

The Open Macintosh is a lot more than just Hardware. 
Consider these few points. If we use Open Macintosh to 
dissolve the functional barriers between micro, mini, and 
mainframe we can get on with the business of creating higher 
quality products and services. Open Macintosh must be able 
to run Systems software like MS-DOS and Unix. [I don't 
agree. -Ed] Unix's environment is hostile, but Open 
Macintosh could (should) make Unix just like a form of 
MAC-OS. This will allow users (US) greater freedom of 
thought, which we will need in the present and future work 
place if we are to be competitive with all the other powers of 
the world. Open Macintosh must use a bus like the VME. 
The fact that few retail sales persons know what to do with a 
VME bus hurts, but this won't Stop those individuals who 
can design total business systems. 

Upgraded 512s and the keyboard 
MACOWACO 

My Monster + has no problem (thanks to DMY!), but 
after trying an Apple upgraded + I find that Draw's control 
characters don't work correctly. I never bothered to try any 
thing else. If your thinking of upgrading your 512 to a plus, 
add the cost of the keybd upgrade, you are gonna need it! 

Boy are my dept's Bernoullis failing! Almost everyone of 
them is getting flaky. One worked okay after a cleaning, 
while another was totally trashed after a cleaning. I am 
sooooo glad I never got one on MY desk! Re AST: please 
continue posting on its performance. I'm probably going to 
be justifying at least one purchase this year and I'd like to 
know if it will go the way of Tecmar's MacDrive (yuck) and 
the printer port Bernoullis (razzzz). I've got an HD20 (yeah!) 
and after 6 months or so, not ONE hangup. 

New Apple Product 
THE PSEUDOHACKER 

I just spoke with a friend of mine who works for a major 
national account of Apple's, ie. a company that buys LOTS 
AND LOTS of computers from Apple. They are also a major 
contractor, like Rockwell, but not quite... Anyway, his 
associates, not him, have SEEN the new Mac. Scheduled to 
debut in January it is supposed to retail for $4000. It will 
have slots, a separate, optional monitor, support up to 8 
megs of RAM on the motherboard and run on a l6mHz 
68020. It will, in other words, cook!! The impression seems 
to be that Apple will position it opposite IBM's AT. Also, it 
will come with an internal hard disk. (I assume a fan will be 
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there too, though he didn't know). Also, according to various 
price lists that Apple releases to its dealers, Major Educational 
Institutions, and Developers, one can read between the lines. 
The Apple Daisy Wheel printer has been discounted for the 
last several months. Now it's gone all together. That implies 
a new product from Apple that will take its place. Also now 
missing on one or more price lists: the 10 mb profile, (though 
the 5mb is still available), the wide Imagewriter and the //c 
flat screen. Rumor in the trades is that a dozen products will 
be announced this September. Besides the //GS, there will 
quite probably be a new // and Mac compatible hard drive, 
(most likely a SCSI drive), and quite possibly new lower-cost 
laser printers. Anyone else heard anything? [Of course, 
they've probably all been introduced by the time you read this!- 
Rusty] 
The New Mac? 
THE ANARCHIST 

I don't really know if the new Mac should even be called 
a MAC, since it also is rumored to run UNIX and MS-DOS 
and have the VERY POPULAR  VME Bus structure for 
expansion. With over 20,000 VME bus devices that are 
already available, it can be just about anything you configure 
it for. Unfortunately, none of the retail salespeople that I 
know will know what to do with such a fabulous machine 
except sell it to run MacPaint and MacWrite. 

Unfragment that disk 
JIM REEKES 

Hard disk slowing down? ALSoft Inc. has just released 
"Disk Express". This jewel claims to unfragment MFS and 
HFS disks by relocating files to contiguous blocks. It can 
purge old icons out of the desktop file and initializes sectors 
still containing data from deleted files (for security reasons). 
It's $30, call ALSoft at (713) 353-4090. 

SIGGRAPH '86 
(name withheld) 

While some of you were fortunate enough to go to 
Boston, I made my way to SIGGRAPH in Dallas. For me, 
computer graphics is an all-consuming passion for the last 
several years; the Mac is one of the best parts of it. Most of 
us have seen incredibly real examples of glass with all of its 
reflective and refractive qualities, the phenomenal 
representation of Jupiter in "2010" and so forth. But every 
year is different, and better. Last year the neat effect was 
blurred motion (temporal anti-aliasing thanks to PIXAR), 
now this year's standard that a lot of the heavies use in their 
demos. This year, the theme was several new approaches to 
animation systems (why I attended) and the ability to render 
cloth incredibly naturally. We're definitely getting past the 
concept of key frames as a computer animation technique. 

Now there are very elegant script and hierarchical-based 
animation systems (kneebone connected to thighbone, etc., 
used to produce Jagger's HARD WOMAN video) (you should 
see what the Cray did to this in 70mm!), to dynamic and even 
behavioral and environmental systems. You can even create a 
flock of birds with the instincts of individual birds, and turn 
them loose, like the owl in the opening sequence of 
"Labyrinth". Mindblowing. 
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Dallas SIGGRAPH was a busy place. A pretty good 
debate about window systems (Microsoft was there, what do 
you expect?) , a demo of "X" ..a distributed network 
environment that lets HP, SUN, VAX, IBM, and more talk 
to each other through windows over Ethernet. Neat. And Alan 
Kay gave a most impressive demonstration of the Vivarium 
project he's been working on. (Take above animation systems 
to create new interfaces, combine with the natural genius of 
children, shake well and watch out!) 

As for hardware, last year it was 68020's, hot 
coprocessors, and the PIXAR. This year they had them 
cranked up to 25kHz, and they actually delivered some of 
Jobs' new machines. Several great new software packages for 
the heavies. From the AT end of things, I thought AT&T's 
TARGA board, and the TI 34010 were slick. I didn't think 
Old Blue's presence hung over the exhibition hall as much as 
it did last year. 

What about the Mac? Well, there were hardly tny there! 
(Except in my hotel room, of course.) Usually they were 
attached to a high-speed laser printer or something. It's too 
bad MGM Station or EZDraft could show Autocad a thing or 
two. But the Mac's presence was definitely felt. I didn't 
know those recolored B&W movies were done on a Mac. I 
heard a bit about the Apollo/Mac system being set up. Lots 
of them were used in courses and panels and an incredible 
number of people said they like them and own them. A 
friend and I decided to initiate a SIG, and with less then one 
day's notice on a bulletin board had a good-sized audience, 
including one of SIGGRAPH's chairmen. 

HINTS OF THINGS TO COME. Silicon Graphics, 
Apollo (and you can bet Sun, too) are working on boards for 
Johnathon. And face it, these folks know how to get power 
into image synthesis! Sun has also been working on a new 
windowing environment using Postscript. Levco is 
working on something with the 34010. Talked to Marc 
Canter at a party. He was "schmoozing" at full speed. He'll 
have a far much more powerful VideoWorks 2.0 out in 
February and some other neat stuff out soon. Dan Sadowski, 
the author of Comicworks, and several other Mac people were 
there checking things out. 

There is a lot of anticipation here that with Johnathon, 
the Mac will start to play a very important role in computer 
graphics. With its anticipated power, open architecture and 
the almost industry-standard 68020, given the user base, it is 
an incredibly attractive package to the hardware and software 
developers here. Next year, SIGGRAPH will be at Anaheim 
July 27-31 - right in Mousehole territory. I really 
recommend it: five stars. 

Rom Bugs «ugh» 
Rusty Hodge 

I don't recall anyone mentioning this: but why does text 
in the editable fields in a dialog box move up and down after 
you have finished editing it? (I guess it only moves down: 
when you go to edit it again, it moves up). Has anyone else 
noticed this? The text edit bug is known at Apple, and since 
it's only cosmetic, they have no plans to fix it. [Apple plans 
to not fix a bug because it is "only cosmetic" Argh! 
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Remember how we all liked the Mac because of the attention 
paid to all the little cosmetic details? -Rusty] 
Excel Notes 
BURRILL SMITH 

Things to watch out for in EXCEL: 

When specifying a pathname in a macro, exceeding the 
Mac OS-allowed 63 characters results in an "Error in Macro" 
message. If you've specified a non-existent file («63 char) the 
macro behaves normally and tells you it can't find the file and 
gives you the Standard File box. Microsoft customer service 
doesn't know about the 63-character limit (at least the ones I 
talked to). The "Bug of the Month" in MacUser last month 
doesn't fully explain the file deleting 'feature' of EXCEL. 
When saving a file, the old copy is deleted first. For example, 
when saving to a too-full disk, EXCEL will save as much as 
it can, then give the message "Disk is full" followed by "File 
Not Saved". What it doesn't say is "File Was Deleted"! You 
must save the file to another disk before closing or exiting, or 
the file will be lost. Another time-saving feature from your 
friends at Microsoft! 

MacApp 
BOB DENNY 

Here are some caveats about MacApp: MacApp provides 
for insulation between the programmer and the event loop. 
This may restrict your ability to do out-of-the-ordinary things. 

Some of the base routines in MacApp are far too slow. The 
simple text editor, for instance, cannot even keep up with 
slow typing. 

ZBasic 
GARY VOTH 


My recommendation is to pass on ZBASIC for now. I 
spoke at some length with their technical rep at the Anaheim 
MACazine show, and he finally convinced me to buy the 
compiler. Since I truly enjoy writing quick applications in 
MS-BASIC, I figured that ZBASIC would be ideal: almost 
as easy and fully compiled... Well, first of all, the 
development environment is terrible. I know the company 
was trying to maintain compatibility with its existing 


products, but that's just death on a Macintosh. What you 
really have to work with is a line editor- pretty decent if 
youre writing code on a 64K CP/M System. It's useless for 
Mac programming. OK, I decided; I would use QUED and 
ZBASIC together in Switcher. This more or less allowed me 
to edit code, but then I tried to compile stuff. The first thing I 
tried was a sample terminal program contained in their 
manual. No workey. It turns out that you can't use ANY 
kind of event trapping (MENUS, DIALOGS, MOUSE, etc.) 
with the INKEY$ statement. This is because doing a MENU 
ON compiles a call to GetNextEvent before every line of your 
code. This removes all KeyDown events from the queue, so 
that INKEY$ never sees them. There is no way to read the 
damn keyboard on the fly while using menus or windows! 
When I reported this "feature" to Michael Gariepy, he was 
defensive and suggested it was a problem with my code. This 
went over real well. However, there may be a fix coming 
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sometime soon. Dave Kelly recently spoke to the guy who 
actually did the coding for the Mac version. He relayed my 
suggestion to return keyboard events through a new DIALOG 
function, something like: C$ = CHRS$(DIALOG(n). The 
programmer said it would be easy to do, so it may show up 
in a future version. [Can someone tell us why they would 
sprinkle GetNextEvent calls all over the place in the first 
place? -Ed] 
TML Pascal... 
MARK MURPHY 

TML Pascal was the first Pascal Compiler that compiled 
to 68000 code, compatible with Lisa Pascal, that was 
available for the Macintosh. This, of course, has made it a 
very popular development system for those of us who prefer 
to program in Pascal on the Mac. Somehow, though, TML 
seems to have escaped any criticism. Don't get me wrong: I 
bought TML and have been using it to develop programs and 
desk accessories. The fact remains though, he compiler could 
do with a lot of improvement. 

MY TML GRIPES [version 1.1 1]: 

1) The compiler does not generate compact code. 

Example: num:= num + 1; is not compiled efficiently. 

2) There is no support to call SANE directly. 

3) The 'vanilla' mode leaves a lot to be desired. It leaves 

a vertical bar at the end of the text and does not provide 

support for backspacing. 

4) When reporting errors, it does not report which 

procedure the error was in. In fact, it gives no indication 

whatsoever where the error occurred - it just informs you 

of the error. 

5) The compiler is not 100% Lisa Pascal compatible. 

6) There are not true Libraries, i.e. it cannot use the 

USES statement. 

7) In 'vanilla' mode, it assumes too much. There should 

be the ability to use standard I/O in ANY window that 

the programmer sets up. 

Also, automatic initialization in ‘vanilla’ mode of the 
Mac Traps should not be assumed. It should be an option. 

There are a few other little items, but they've slipped my 
mind right now. TML may have good competition in the near 
future (Apple's MPW, Lightspeed Pascal, and Turbo Pascal). 
Then TML won't be the only Pascal compiler in the woods! 
The others coming out have some real good features. Let us 
be grateful for the first Pascal compiler on the market, but 
lets not worship it, as I have seen some Mac Developers do. 

[I disagree with some of these items. The code generation 
is very efficient, more so than LightSpeed Pascal and pretty 
darn near 10046 Lisa compatible, again, much more so than 
LightSpeed Pascal. Plus version 2 is rumored to run twice as 
fast as the compiler efficiency has been improved, and it 
supports both units and objects! -Ed] 

LightSpeed Pascal 
THE ATOM 

Got my Lightspeed Pascal in the mail today.. After 
working with it for about 5 hours, I'm fairly impressed. It 
took a while to convert my TML code over. The code all 
worked fine, but my program was around 4000 lines long and 
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I had to segment it up into 3 or 4 parts, since the LS doesn't 
want you to have more than 2000 lines in a Unit. The 
debugging is great! Like the MacPascal debuggers plus a 
assembly debugger called LightsBug which works very well. 

It does have a few quirks though. A record in which I 
stored data in TML returned a size of 5336 bytes, but the same 
record on LS gave me 5436 bytes. Where is the missing 100 
bytes? I can't figure it out, but it sure did screw up my 
Save/Open options that were reading 5336 byte files and 
giving Eof errors. One other thing I haven't figured out yet: 
when I go to my About box routine, I set up a window with 
NewWindow, then wait for a Mousedown event to exit. It 
works fine in the compiler/debugging mode, but when I 
compile it to an application it gives me a system error ID=11 
after you click to exit the about box. Any answers? [Check 
the compiler option that controls who does the quickdraw and 
window initialization, you or LightSpeed. Try $I- option. -Ed] 

Data Frame Drives 
David Smith 

Had a talk with Steve Edelman, President of SuperMac 
Technology, about their Data Frame 20 hard disk. It seems 
that Walt at Coast Computer has returned his store's entire 
inventory of Data Frame drives and put a hold on further orders 
until he could get units with Seagate drives in them. He said 
he was getting too high a return rate on customer delivered 
units with the MicroSci drive. Steve Edelman said they use 
three different drives, the MicroSci, Seagate and La Pine drive, 
the last one being a newcomer. The drive manufactures claim 
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their drives give a 1-3% failure rate, but surverys of store 
managers claim its more like 10 to 15%. And this isn't unique 
to SuperMac or any other vender, but a problem across the 
board. The drive makers just don't deliver consistant quality 
control from one batch of drives to another. Steve said they do 
extensive QA and burn-in to weed out any bad drives but still 
problems tend to come in cycles. He also clarified the OMTI 
controller board situtation. It seems from May to July, a 
terminating resistor pack was changed by one of the vendors 
that didn't make good contact with the motherboard, leaving 
the bus unterminated. The vendor has been replaced, the OMTI 
boards are fine now and they've seen no problems since then. 
Several other hard disk products also use the OMTI interface. 
So, I don't know why Walt is down on the unit, but after 
talking to Steve, I decided to lay down my money and takes 
me chances! 

Oh yes, he also explained what the XP is all about. What 
they do is provide a daughter board that plugs into the Mac 
Rom slots, and you plug the Roms into the daughter board. 
On the board is a small Rom with a custom SCSI driver. An 
INIT resource changes the pointers to the custom SCSI driver 
so the XP drive runs at twice the normal SCSI port speed. 
Since each SCSI device uses its own driver, this does not 
effect other chained devices. Any data frame can be upgraded by 
buying this daughter board and inserting it in the Mac. The 
two drive units are essentially the same. Only the Mac SCSI 
driver software has been speeded up. 
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Mousehole Report 
MPW & LightSpeed Pascal 


To join, send SASE to Rusty Hodge 


WORD 
Tax Free 


Thought you might like a peek on the progress of 
Microsoft Word 3.0. I know, I know. Up to now it was 
Word 2.0, but it appears Microsoft feels the jump all the way 
to 3.0 is warranted. I think they are right. Even the first beta 
shows the outstanding level of design and performance 
improvements. Some of the features are already public record 
(built-in spell checking, outlining, etc.) but a lot of the 
subtleties must be seen to be believed. The outlining is 
completely interactive with the text, making idea editing not 
only easy, but promoting a new level of working with 
writing tools. It is fantastic. Goodbye and good riddance to 
ThinkTank, Acta. (Welcome to More, though.) 

The spell checker has dictionary-based hyphenization. 
There is moderate kerning control. There are style sheets (like 
in the upcoming Pagemaker 2.0) that make for powerful 
formatting ability. There is a preview page function that 
really gives you a lot of control over your document's final 
appearance, and a clever way to insert page numbers anywhere 
you want automatically, as well as built-in indexing, table of 
contents, line numbering, etc. Built-in graphics ability for 
lines, boxes, etc. Nice pagination, and some of the best 
features: real interactive rulers and customizable menus. 

And much, much, more, of course. Very well done, very 
well thought out. And it's a joy to use (when it stops 
crashing). All indications are for a long and careful test period 
to fix everything right. Microsoft really wants this one to be 
right, like Excel. There's lot of competition, what with Word 
Perfect and all, but the competition's going to have a hard 
time of it given Microsoft's expertise with the Mac interface 
Showing up so superbly. This is one incredibly powerful 
program and is thrilling to use. It is also hungry: it uses up 
625K of RAM and takes up 2 disks. If they have an offer for 
an upgrade....do it! 


Hard Disk Shutdown 
Rusty Hodge 

Corsair showed me something on the Dataframe. If you 
do a shutdown and then turn off the Mac after the beep, when 
you re-turn it on, the Dataframe and the ProApp and 
apparently all the other drives will boot in about 20 seconds 
less time. *If* you turn off without shutting down (or even 
just reset), it will take 20-30 or so seconds to do something, 
who knows what, before it boots. What magic thing happens 
if you do a shutdown? You got me, but not doing it must 
cause some sort of disk media check. 
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Rusty Hodge 
Contributing Editor 
Mousehole BBS Sys Op 
PO Box 2323 

Orange, CA 92669 


That's Why 
Randy Saunders 

For all HFS volumes there is a thingy in the volume 
header called the "clean dismount" indicator. This tells the file 
system that the disk was correctly updated before it was 
ejected. If this is not on then when a volume is mounted, the 
file system goes out and checks the catalog B-tree and extents 
B-tree to make sure they don't have any apparent damage. I 
don't think it can do much to fix it, and none of my disks 
have ever failed, but you probably get a cute bomb box. 

When a disk is first written to, the "clean dismount" is 
reset. If you tum your Mac off it never gets set back on, and 
the file system does its little number for 10-15 seconds (for 20 
MB). If you don't have RAM cache on, you almost assuredly 
have good stuff on disk, but the power could have failed while 
you were copying folders (or some busted program could have 
hosed things) so it's really not safe to assume the disk is OK 
when it only takes 10 seconds to check. 

By the way, I never turn my hard disks off. They take 30 
seconds to spin up and that's a lot more time than the mount 
check takes. I just select "Shutdown" and hold the mouse 
down and turn the MAC off. One blink of the active light it 
probably a seek to the index track because the controller has 
noticed that the MAC is off-line. I have had a lot more disks 
fail at start-up than any other time (we have lots of ST-506 
disks where I work, not only in Macs). 

TOPMAIL & Mac Rumors 
Macowaco 

Finally got it and it was worth the wait. It's got all that 
Inbox has except for the expensive and unnecessary bells and 
whistles. AND nobody has to give up a Mac! Only, it won't 
install on a HD20 and sometimes it won't install on a floppy. 
No matter what I do I can't find why...oh well. It works fine 
with MacServe, which by the way seems to be on its way to 
being the one to beat in the server game. Nobody can out do 
it for the price. A good solid combination, MacServe, 
TopMail.... and Mazewars (which won't work with Macserve!) 
[Due to the fact that MacServe has problems with HFS, we 
think TOPS from Centram Systems may be best. -Ed] 

As for rumors, I haven't dropped any lately so I thought 
now is a good time... Apple is gonna Stop on release of the 
new big one, but will go ahead with the new smaller one with 
the 68020 in it. The rumor is Apple is gonna put the 68030 
in the biggie. Oh my, 8 MIPS.... The talk now is of two 
product lines. The first is the compact line which consists of 
the closed machines; Mac 512E, Mac+, IIc.... small footprint 
and low cost. 

The second are the soon-to-be-expandables that we've all 
been drooling about... 68020 at 16 (!!!) Mhz (sounds like 2 
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mips). The ROM will include color quickdraw routines and 
will be 256K. It will come with 1 meg. 256K SIMMS, but 
enough room for expansion up to 1.4 GIGABYTES (!). The 
internal bus ain't VME (sigh) instead they're going with a bus 
developed by MIT and bought by TI... it don't need no 
dipswitches. They're gonna use a Foley sound chip which has 
only four voices and won't be as powerful as the GS's: they 
think this machine won't need it. It'll come with a 12" 
monochrome, 73dpi at 640/480, a later release of a color 13" 
monitor with the same resolution. 6 slots with one used for 
the monitor leaving five for the user. 2 SCSIs with one 
internal (!) and the external using the DB25. Two serials ext. 
using the Din8s. Another later release will be a 19" color 
with 1280/960 for 88dpi. Expansion cards will include a 
68551 Motorola MMU and a 6881 at 16 Mhz. A 5.25" DD 
will be available with SW for MS-DOS file compatibility. A 
third party is working on a 286 card which will use the 
5.25DD for full MS-DOS application compatibility. 

They are also working on a 386 and an RT emulator 
(WHY RT??? Its a flop!) It'll have Unix v5.2 with the 
Berkeley 4.2 stuff in it, and itis AT&T approved. Quickdraw 
commands in portable C for UNIX compatibility. 

ALL BY MARCH 1987! 

Other things include a definite Appletalk File Server 
which will not be anything like the 3COM. Confirmed 
laying of Appletalk protocol on top of Ethernet. They are 
looking more at the DEC market than the IBM (smart). 
MSWord 3.0 will have a DCA filter and I'm told it will allow 
one to create full document compatibility with Mainframe 
systems. 

Now for what I think is Science Fiction.... 

A fiberoptic Appletalk setup which will deliver Mazewars 
at 20 Mbits/sec (!) due late 87 or early 88.... the 68030 one 
year from next release, and... 68040 two years from next 
release. 

I'm sure there was a lot more, BUT SINCE I WASN'T 
THERE I DONT KNOW. HINT! However, if I was there I 
would have signed something that would have forbidden me 
from dropping all these shoes. 

NuBus 
Frank Henriquez 

Oh please! Not the NuBus! That's the only MIT-TI bus I 
know of, and it doesn't compare to VME. Well, you wouldnt 
expect Apple to follow any established standards... 

Roll Out Date for New Mac 
Mike Steiner 

When I was at Apple, Phoenix for RSP training on the 
//GS, I said to the trainer, "See you in January." He asked, 
"Why?" and I replied, "for the new Mac training." He said that 
he'd see me in March in that case. Guess that March will be 
when the new Mac sees public light. 

Laserwriter Trix 
Richard Clark 

Most of you LaserWriter hacks out there know about the 
"command-F" trick to get the PostScript command file for 
your document instead of the document itself. (Oops - clumsy 
phrasing. Command-F puts the PostScript file on disk that 
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the LaserWriter would otherwise use in printing your 
document.) 

But, I haven't heard any mention of "Command-K", 
which dumps the current PREP file into a text file called 
PostScript. (Try it - youll get a TEXT file containing the 
code sent from Laser Prep.) This means no more fooling 
around with FEdit to see the prep file. [Interestingly enough, 
you can download the cmd-F postscript file with a postscript 
dumper program and it will run correctly, calling the 
LaserPrep file if necessary. But if you download the cmd-K 
file, thinking it contains both the LaserPrep header and your 
file, the LaserWriter hangs up! Anybody know why? -Ed] 


Final Revision of MacDrive Software 
Beaker 

I can contirm that (as published in MacTutor) there WILL 
be a version 2.3 of the Tecmar MacDrive software. I know 
because I have it. I'll. be receiving the second beta version of 
it this week. 

As reported by me earlier, it does "fix" the Imagewriter 
problem. What that means, unfortunately, is that now it 
doesn't hang when the Imagewriter tries to talk back, it only 
absorbs the data. So you STILL can't do color printing, etc., 
but you CAN use the Imagewriter 2.3 (which is faster). 

The driver software DOES support larger drives (up to the 
capacity of the ZEBEC controller). Unfortunately, it is still 
not known whether the Volume Manager will be fortified to 
handle the larger drives. If not, then forget it, since the Vmgr 
is the only way to create the necessary partitions. I'm urging 
them on HARD. (Dave told me that if you replace the 
controller, you could do something disgusting, like shove a 
Maxtor 1140 or even a new 380MB Maxtor in there - YUM!) 


Tecmar will be distributing a pretty neat backup program 
called FullBack with the new software. You'll like it. It was 
written for their large drive, which may or may not ever see 
the light of day, but thats a whole other story. 

The final (bad) news is that this won't be a free upgrade. 
It'll cost, but I'm not sure how much (it won't be bad 
though). I'll let you know on the saga of larger drives. 

HyperDrive FX-20 
The Anarchist 

After using the new Hyperdrive FX-20 for a couple of 
weeks, I can tell all of you that I am very pleased with it. If 
the case design doesn't offend you (about half my friends like 
it and the other half can't decide) then this is one heck of a 
drive. 

It comes with the typical HyperDrive ‘Security’, 
'Backup/Restore' (which is now HFS-Rated) and a *NEW* 
LaserSpooler' DA. It retails for $1195.00, and can be had for 
about $1000.00 at your local store. It is about the same price 
as many of the other 20 meg drives, but I would suggest this 
one since GCC is a manufacturer that will be around to 
support you when the others are gone. 

Also, the new HyperDrive 10 and 20 software release is 
out, and it is pretty nice. It is version v3rl, and has the 
LaserSpooler DA too! If you have an internal HyperDrive in 
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your Mac or Mac+ drop by your dealer with three fresh disks 
and get this worthwhile free software upgrade. 
Protect Bit 
Chief Wizard 

The protect bit works differently on MFS and HES. To 
change it with MFS, you have to read the catalog directly and 
adjust the flag byte manually and write it back out. In HFS, 
you have to do something similar, but I think they've 
MOVED the protect bit. You should play with FEdit and find 
out where the protect bit is now located. There is no way to 
clear the protect bit with any SetFileInfo type calls. The 
resource file name is NOT kept around anywhere. The only 
thing I could recommend would be to scan the files (you can 
find out what volume it's in) and compare the location of each 
file to the locations associated with the path of the file you 
want. 

[HD Util allows you to change the protect bit, unlike 
ResEdit and Fedit, which only let you see the state of the 
protect bit. - Laser Dolphin] 

Paper Jamming 
Jim Reekes 

If you have an ImageWriter // and the paper jams, it's 
probably getting stuck under the paper out sensor. Have your 
favorite dealer order a BUNCH of "paper out sensor frames" 
from Apple. They'll most likely be on back order, so you'll 
have to wait, but they only cost $10-15. This bugger has 
caused just about every ImageWriter // owner to kick and spit 
while trying to get a single page to print. 

Button Help 
The Atom 

Here's the new question: I have a dialog (made with 
rmaker) that loads up with GetNewDialog. I've got my OK 
and Cancel buttons as the first two items. When you hit 
return, it does the OK button just likes it's supposed to. The 
question is, how do I tell it to put a double line border around 
the default button (the OK)? 


The only way I know how to get a button to have a 
double border is to draw the outer (heavy) border with 
DrawRoundRect; it is not part of a button definition. (Boy, if 
I'm wrong, I'm gonna get a lot of flak about this one!) - Mike 
Steiner 


There are a couple of issues involved here. (And you 
thought it was a simple cosmetic matter. Oh well, that's the 
Mac). First, if you are SURE you're never going to get any 
update events, you can just draw the roundRect manually by 
setting the port to the dialog window and doing it. But you 
Should first do a DrawDialog so it won't get wiped out when 
the dialog manager draws the dialog later. 

If you ARE going to have to deal with normal update 
events (and solve for the general case anyway), you have to 
make the thick line a user item. BUT, make sure to place it 
in the item AFTER the okay button itself. Otherwise, when 
the dialog manager scans the item list to find out where a 
mousedown occurred, it will hit the disabled user item before 
finding the okay button and it will stop. 
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To make a user item, do your GetNewDialog, then do 
GetDItem and SetDItem. For the itemHandle parameter, pass 
a pointer to a procedure to draw the outline. The parameters for 
a user item procedure are listed in IM. - Chief Wizard 


Of course if the default button is the "OK" button no 
border is necessary. On the other hand if you want a border 
anyway, and your dialog could be an alert instead, you will 
automatically get either the first "OK" or second "Cancel" 
outlined depending on your alert template. - DonL 


Here's a routine I use to outline my OK buttons in Modal 
dialogs. Just pass in the DialogPtr, item number and corner 
radius for the outline (16 is std.) and you've got it. As far as 
the updates go, you could call this from a filter routine 
everytime the filter gets an update event. This way you'll be 
sure to always have the outline around.  - Rick Boarman 


PROCEDURE OutlineButton(theDialog: DialogPtr; itemNo, 
cornerRad: integer); 


( Draws a border around a button. 16 is the normal 
cornerRad for small buttons ) 
VAR 
itemType: Integer; 
itemBox: Rect; 
itemHdl: Handle; 
tempPort: GrafPtr; 
BEGIN 
GetPort(tempPort); 
SetPort(theDialog); 
GetDltem(theDialog, itemNo, itemType, itemHdl, 
itemBox); 
PenSize(3, 3); 
InSetRect(itemBox, -4, -4); 
FrameRoundRect(itemBox, cornerRad, cornerRad); 
PenSize(1, 1); 
SetPort(tempPort); 
END; 
Lightspeed... 
Gary Voth 
“You've come a long way baby..." That's the first thing 
I could think of to say after getting a look at Think 
Technologies' LS Pascal at Dave Kelly's the other night. The 
source-level tracing, breakpointing, immediate statement 
compilation and variable observation make this product damn 
near as easy to work in as an interpreter. The pretty-printing 
editor is great too! I've long been spoiled by some of the 
features of MS-BASIC and Macintosh Pascal editors, such as 
automatic indentation, keyword boldfacing, and so on. Now 
you can get it in Lightspeed. Still doesn't work with Mac 
Plus cursor keys, though. 
LS Pascal Problem 
Yes like Gary said... it's great. So far I've been really 
having fun with it. One problem I noticed that maybe you 
experienced Pascal people can figure out. If not maybe there 
isn't a fix?? I tried running some of the very first MacTutor 
Pascal stuff (from Vol. 1) Well, Alan Wooton's READING 
PAINT FILES' program won't compile because Lightspeed 
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won't let you have variables the size of a paint file. The 
manual states that the largest size a variable can be is 32767 
bytes because of something to do with the way the 68000 does 
offsets (whatever that means). (Alan set up an array to hold 
the bit map for the screen that is about 55K.) OK, Alan, how 
about a way to do it? Or should we all complain to Think 
Technologies? Except for this I see no problems with 
Lightspeed Pascal. -Dave Kelly 

Lightspeed C is undergoing a revision and should be out 
in November as version 1.5. It doesn't have the Pascal source 
code debugger, but a lot of the nice HFS features of the Pascal 
product have been added to the C product, making it more user 
friendly. -David Smith 

MPW 
Micro Ghoul 

I recently ordered MPW (at horrid prices, I might add), 
and am now wondering (as I anxiously await its arrival) what 
other people think of it. 

I have been working on both the Xerox 1186 using 
Common Loops (we are a Beta Site) and Sun 3 with Objective 
C which, of course, have very different approachs and 
implementations of the OOP paradigm. (Side note: if you're 
interested in seeing Objective C for the Mac, call PPI: they are 
very interested in your thoughts!) I have read the Hayden book 
Object Oriented Programming for the Macintosh, which I 
thought was interesting though often a bit wordy (I am always 
in a rush when trying to get info, so just give it to me 
straight!), but I did not get a strong feel for the programming 
environment itself. Does anyone out there have enough 
experience with MPW to comment on it? I purchased all of 
the parts (for kicks, I suppose, as that gives me 3 C's and 3 
Pascal's and 2 assemblers!), but I did it, basically on the 
thought that the potential for the product was high enough to 
chance it. Though I did not like being told that I was not 
entitled to a discount on upgrades or actual purchase! 

MPW Feedback - Rick Boarman 

To start with, MPW is not for the light of heart, casual 
or easily frustrated programmer. [That let's me out! -Ed) Using 
it is easy, but mastering it can take many months. I've been 
using it steadily for six months now and still learn new 
commands and ways of doing things. MPW consists of the 
MPW Shell (Editor) and numerous Tools. Each tool 
(command) is activated by entering its name into any window 
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in the Shell and hitting the Enter key. Typical tools are the 
Compilers, cross referencers, Linkers, editing commands, file 
IO, folder and volume commands, and custom commands of 
your own. 

A typical command to compile, link, resource compile 
and execute a Pascal program might look like this: Pascal 
Sample.p Link Sample.p.o {OBJLibraries} -o 
Sample.code Rez Types.r Sample.r -o Sample 
Sample. [You mean I gotta learn to type again? -Ed] If this 
whole mess is selected and executed, Sample.p will be 
compiled and linked with the object files specified in the 
variable (OBJLibraries). The output of the link will be saved 
in Sample.code. Then the resource compiler (Rez) will do its 
job and put the output in Sample. Sample is now an 
executable Mac application. The last line launches Sample 
and actually leaves the Shell completely. When 
! ExitToShell is executed from Sample, the Shell starts up 
again right where you left off. All windows are in the same 
place, selections are the same..... 

There is no debugging per se. MacsBug and TMON are 
still the best for that. One real slick command allows custom 
menu commands and menus to be added to the Shell. For 
instance, I have a Menu command to read all .p files in a 
folder, put each file name in a menu as an item. When the file 
name is selected from the menu, that file is opened. Real 
Slick, since I have three folders of source code, with about 
fifteen files in each. 

MPW provides 10096 toolbox compatibility. All calls 
are implemented. The version I have (1.0B2) is still fairly 
buggy and likes to bomb at times. Compile times are fair. 
About 10% faster than Lisa Workshop, but still very slow 
compared to LightSpeed. One of my programs has nine 
UNITS with about 75,000 lines of code. It takes 32 minutes 
to compile compared with 45+ on the Lisa. The learning 
curve is several hours. But to master what are called 'Make 
Files, which handle automatic application-building based on 
modification dates, takes many hours of frustrating work. At 
least this was in my case, as I have many folders and files to 
juggle and NO examples of how this is supposed done. The 
latest manual has examples of this - too late for me though. 
[Watch for a special MPW and MacApp issue of MacTutor in 
the very near future. -Ed.] zw 
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The Mousehole Report 


Pics on the New Macs 


Rusty Hodge 
Contributing Editor 
Mousehole BBS Sys Op 
PO Box 2323 


Orange, CA 92669 
The One and Only Original Mousehole. 


To join, send SASE to Rusty Hodge. 
Sysop Speaks 
Rusty Hodge 

Merry Christmas! This Christmas season the 
new Apple //gs should be a big hit. But in January 
we should be seeing the first of Apple's exciting new 
line of Macs. The "Aladdin" will be surprisingly 
similar to Levco's Prodigy, including a DMA'd SCSI 
port. (DMA = FAST) 

Speaking of the //gs and the new Macs, look for 
Apple's Desktop Bus to start popping up in the Mac 
family. This means your mouse will plug into your 
keyboard, among other things. 

This month we're featuring a segment on "Pascal 
Wars". Who wins? Decide for yourself. As of this 
writing, Turbo Pascal was just released, so it's getting 
a brief critique, not one based on experienced use. 

Finally a few months ago, someone mentioned 
that QUED had a 32K limit on file sizes. The 
authors dropped me a note about this. QUED actually 
doesn't have a limit (aside from the amount of RAM 
in your Mac). I put together the report using QUED 
this month. It is a very fast text editor, had no 
trouble dealing with a 100K or so long file, and I 
think I'll start using it as the basis of comparison 
with other editors. (If you switch editors and have a 
lot of files created with the old one, get Text Ranger, 
an application that will change the creator of all text 
files to whatever you specify, i.e. QUED.) 


Disk First Aid 
The Atom 

Don't know about anyone else, but Disk Express told me 
my Dataframe had too many blocks allocated and thus 
wouldn't compact the desktop or prioritize files. But this great 
Disk First Aid program solves that! Just run disk first aid on 
the HD, then run Disk Express. No errors and no more 
fragmented files! (Of course Disk Express still takes 2 hours 
on a 20-meg HD to prioritize and unfragment). 

Also, if you haven't gotten it yet, the release of the 
Dataframe print spooler 3.0d is out. Registered owners should 
get it soon. Also with the spooler is a head parking program 
you can run before you transport your hard drive anywhere. 


TextEdit Problem (New ROMs?) 
Go 
I can't seem to get a blinking cursor when I type 


characters in my program's TextEdit window. I call TEIdle in 
the main event loop, and I make sure the port is active, and 
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Paris - Workstation 


Paris - Color 


Macintosh Plus 
HD20-SC 


Macintosh Plus 


€ The 1987 Macintosh Product Family € 


when I click the mouse (TEClick) it starts to blink, but as 
soon as I start to type (TEKey) the cursor vanishes! I've 
noticed the same problem in my friend's editor and the 
MockWrite DA, so I know the problem is not unique to my 
program. [This is a bug in the new ROMS. A call to 
TEScroll with dh and dv both 0 results in loss of the insertion 
point. See Tech Note 22 and only call TEScroll when there 
really is something to scroll. Compare your event loop to this 
month's Text Edit Demo, which does not have the problem. - 
Ed] 

Deep Folders 

Jim Reekes 

Late one night Rusty and I were backing up 20megs to 

another drive. I've done this many times in the past without 
losing a file. This time I think we discovered a nasty problem 
with HFS. There was one folder that had several folders 
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within folders. I think it was about 10 or so deep. When we 
attempted to copy this folder, it wasted the directory structure. 
Ouch! Kinda like the problem ProDOS has if you've got 15 
or more sub-directories. Look out for this bug. Oh yeah. 
After copying a few hundred or more files, you MUST reboot 
the Mac. It doesn't do much of anything right after a mass file 
transfer. 


Folders and Mouse Freezing 
Cpettus 

Some time ago I remember a message in which a 
downloaded program was accused of causing a "deadly folder" 
to appear on a hard disk: the mouse would freeze and the 
system lock up when this folder was opened in the Finder. It 
just recently happened to me, but in entirely different circm- 
stances, and I suspect the actual culprit is the HFS directory 
information not being correctly written out to disk when the 
system crashes (because it's still sitting in one cache or 
another). The Mac is supposed to go through a rebuild 
procedure on a volume which was not correctly dismounted 
when it encounters it again, but this is apparently not as 
robust as it could be. [If you have confirmation of strange 
Finder problems like this, please write to MacTutor so we can 
present them to Apple. -Ed.] 


LoDown Problem 
Burrill Smith 

For those of you who are looking for a fast HD at a 
reasonable price, as I was, think twice before considering 
LoDown. Three days after I got mine, the controller board 
went out. OK, not their fault, these things happen. However 
this was three weeks ago and I'm supposed to get it back 
today. It took them a week to send me an empty box so I 
could send it back to them (their rules, no LODOWN box, no 
warranty). If you plan to become dependent on your hard disk, 
I suggest you find a supplier who offers service, which 
LoDOWN doesn't seem to. [I can add a good story to this. We 
got a 20-meg LoDown box at a place I worked once. It never 
seemed entirely on the ball and was the loudest HD I'd ever 
heard. One day, it began to whine more loudly, then to 
screech, and as we raced to unplug the thing, it was screaming. 
SMOKE was actually coming out the back. We uh, returned 
this evaluation drive. -- Laurel Galvan-MacLean] 


All's Fair in Love & War 
David Smith 

I couldnt let the previous post go by without 
commenting on our experience with DataFrame. We bought 
two DataFrame 20's. One had a microsci drive in it that was 
very quiet. Couldn't be heard over my LaserWriter. The other 
had a seagate drive in it that sounded like an aircraft carrier. It 
was a definite hum over the LaserWriter. Plus it was dead on 
arrival. The microsci DataFrame has worked without any 
problem or data loss for several months. A problem we 
reported last month with our Mac was due to the Max2 2-Meg 
memory upgrade boards coming lose. This required several 
trips to a dealer to seat the simm modules more securely and 
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now the Mac seems fine. Watch out for this problem. In any 
case, the DataFrame has seemed very reliable and robust. The 
drive that was returned was finally fixed and sent back to us 
and works fine, but still hums. I mention all this to balance 
the above post on the LoDown which I believe is also a fine 
drive. I also recommend re-formatting your drive on arrival to 
catch any bad spots after shipping. 


File Tags 
Chief Wizard 

The file tags were supposedly going to help people 
rebuild trashed disks, but no one ever came out with a good 
utility to do this. Also, there was the annoying fact that with 
file tags, your sectors were 524 bytes long instead of 512 
bytes long. This gave HD maufacturers some trouble. Apple 
has decided that the tag bytes are pretty useless, and will not 
be in any future products. (Guaranteed sector size of 512 
bytes.) 


Cautious on MacExpress 
Cpettus 

Ive been using MacExpress (backing up before each 
application). Comments so far: 

l. It's very, very, very slow. Not that it doesn't have 
reason to be (in most circumstances, it has to move 80%+ of 
the disk around to get it into the structure it thinks optimal), 
but it does give a large "window of opportunity" for the power 
to glitch (for example) while the disk volume is inconsistent. 


2. I'm not sure how thorough the diagnostics features are. 
It does not, for example, detect a corrupted desktop file (or at 
least the kind of corruptions that I had). 

3. It resets the modified dates on all moved files, 
preventing most backup utilities from performing incremental 
backups . after the MacExpress is complete. 

Finally, I have no proof of any problems with it, but I 
have (sooner or later) encountered problems with either the 
HFS structure or the desktop after using MacExpress. Use the 
same caution with it that you would with any application 
which is (a) in its first release, and (b) directly rewrites the 
control structures on your disk! 


SCSI Disk Icon 
Burrill Smith 
Where does the icon for my SCSI drive come from? I 
can't find it anywhere with ResEdit, and it's driving me crazy 
with its ugliness! 


[A volume driver must respond to one of two calls from 
the system. It must either respond to the call requesting the 
resource ID number of its icon in the system file, or it must 
respond to the call requesting a pointer to an ICN# resource in 
memory and a "Where" string (for the Get Info Box). Since it's 
much easier for the driver to just declare the data within itself 
than to get something into the System, the second method is 
the most common. (And besides, thats how Bryan Stearns' 
example SCSI driver did it.) 
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If you want to change it, you've got a problem. The 
SCSI driver is loaded from the drive itself at boot time. BUT 
the area where the driver resides is not accessible with FEdit. It 
doesn't actually exist within the volume's data space. You 
should be able to find the icon data in memory within the 
driver code, though. Once you've done that, you should also be 
able to patch the disk initializer program that is usually 
shipped with each SCSI drive. 

The disk initializer is what puts the driver and the boot 
info onto the disk. After you've changed the icon, reinit your 
disk, and viola! ] -- Chief Wizard 

Thanks for the explanation, Wiz. I had found the icon in 
the format utility, but as you say it was data, not a resource. 
You also cleared up the mystery of how ‘Get Info' knew the 
manufacturer of my SCSI drive. Until I need to reformat 
(NEED TO? Never, I hope) here's my workaround: 

When in the finder, the SCSI icon becomes an ICN# 
resource in memory, ID # -33. So I placed an ICN# -33 into 
the Finder's resource file and it replaces the SCSI icon. 
Apparently the SCSI driver queries the drive before it loads the 
Finder. A side effect is that Get Info says the volume is 
located on AppleTalk rather than SCSI. --Burrill Smith 


Likes MacExpress 
Jim Reekes 

I've found that MacExpress became a utility I can't live 
without. It has cleaned up some of the fragmented-est 
Situations I've seen. If you have any questions I can ask the 
guy who wrote it. I got to met him in Dallas MacExpo. He 
is interested in any comments that I may pass along to him. 
I'll ask about his readjusting of a file's mod date. I do know 
that it does not claim to "re-build" a disk's directory - I don't 
think anything could. 

Secondly, if you manually build a new desktop (holding 

Comm-Option during boot) you will lose comments and some 
ICONs. MacExpress will preserve both of these. In general, 
it moves applications toward the logical ‘front’ of the drive, 
then places documents afterward, and finally spaces at the 
rear’. 
"DiskExpress does not alter the file's modification date", 
according to the programmer that wrote it. I Expressed’ this 
morning and found no dates changed. ^ DiskExpress only 
moves a file 'one block at a time' to a new location, then 
updates the directory. Sure, this is risky business during a 
thunderstorm, but any failure to update the directory would be. 
(Like getting the bomb during a long session with Microsoft 
Word). 

Anyway, how long DiskExpress takes to do this depends 
on the fragmentation index. (Do not trust 'FEdit' for a proper 
index). I tend to Express on a regular basis, and generally this 
takes about five minutes to complete. If your drive is "way 
rad", then it's gonna take longer. It can repair some directory 
problems, too. HFS has problems remembering the proper 
number of blocks for a file. DiskExpress will "remind" the 
Mac how many there really are. Make sure you have the latest 
version, 1.06. If you are having problems with the copy you 
purchased or would like to, call them at 713-353-4090. 
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Express and MacServe 
Macowaco 

If you were an early Macserve manager you would 
remember Infosphere's comments about fragmentation and 
server performance. While their direction (put in your 
Macserve volumes first and don't change them) helped initially 
MacExpress (and HD first Aid!!!) really make a difference. You 
can even Express within the volumes for even more speed. 
Although it does take quite a while the first time, Infosphere 
Should put their own version into the Server manager 
software. Something weird happened with the PD Laserprint. 
You know the DA that sends the postscript file. I sent a small 
sample to the Laserwriter and it stuck it into the middle of a 
friend's 12 page printout. The two lines that I typed on my 
sample were "Hi Bozo!" I couldn't find the printout until I 
heard the guy next door bust up, then come running into my 
office demanding to know how I did it. What was weirdest 
was that he knew I did it. 


Jazz Bug Fixes 
Gary Voth 

There is an INIT resource available on MAUG and in the 
LOTUS JAZZ forum that fixes an incompatibility between 
JAZZ 1A and Apple System 3.2. The new system software 
causes a "Serial port is in use" error in the JAZZ 
communications module. The file is called "SYST32.FIX" 
and is in DL1. JAZZ isn't the only communications software 
to have problems after Apple released the new ROMs and 
System files. MicroPhone is completely useless for text file 
uploads. I only wish the Software Ventures (read Dennis 
Brothers) would be as considerate about the problem as Lotus 
has been. 

Microsoft Word 
Tim Celeski 

By the time you read this, Microsoft will have made their 
formal announcement on the new version of Word for the 
Mac. They will also announce their update policy for those of 
you that already own it. As someone had mentioned, the new 
version is much, much more powerfull then the existing 
version, and starts to have Desktop Publishing like features. 
A really nice piece of work. 


Nubus is Better than Vme 
Zenomorph 

Hello All, I can stand the waiting so I going to spill 
more on the Nubus. Did you know that Nubus has a 10 Mhz 
clock in sycn mode. So you already knew that! Well did you 
know that this means that processors running on this Nubus 
can run at up to 40 MHZ. That's Flamming faster than the 
new secret DEC VAX bus. Ah, well if I'm not mistaken it's a 
lot faster than the VME, and NuBus is very INEXPENSIVE 
compared to VME. The VME bus is complex but the Nubus 
is SIMPLE; very SIMPLE. This means that add on boards 
will abound. [But is the Mac bus really a Nubus? I've heard 
rumors that it differs slightly. -Ed.] 
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Comdex Mac Rumors 
Macgeorge 
I have it that Apple has cancelled out of Comdex Las 
Vegas and showed up in Atlanta with the new toys. Top of the 
line machine is a UNIX machine with a 30 meg storage 
system (yes 30 !). The SCSI interface may be in for some 
competition from a new generation interface. 


Microphone Bugs 
Gary Voth 

What's with the bugs in MicroPhone's text file upload? 
This is the one where you get echo characters and double lines 
on screen. I know Jim Reekes has experienced this same 
problem, but I don't hear a lot of complaining about it. It 
makes it almost useless for sending messages to the 
MouseHole. Anybody know whether this has been fixed? 

(This problem is only on the local display. Text actually 
uploads correctly. See previous post about system 3.2 
problem with Jazz. - Rusty) 


Pro3D 
Macowaco 

A new upgrade of Easy3D. While the user interface in the 
front of the program is identical to Easy3D this is definitely 
not the same program. Drawings are scaled for accurate 
drafting, a new profile generator makes detailed 3D possible, 
but best of all is the way it makes the Laserwriter do its work. 
The output is breathtaking. The grey scales are fantastic. Well 
worth a 15-30 minute wait to print something. It takes 
GEOMOD on a dedicated VAX at least that long while I don't 
think the output is as good. It might be the 3D winner. 


Core Edit on MacApp 
Micro Ghoul 

Ciao, I have been playing with MPW and MacApp for a 
little bit now, and have started (read thought out what I want 
to accomplish) to work on encapsulating Core Edit into 
MacApp. Has anyone tried this? Has anyone failed at this and 
has a reason why? Finally, does anyone know whether or not 
Apple plans adding Core Edit features to the current text tools 
(I doubt it, but it does not hurt to ask)? [MacTutor is very 
interested in this project of getting a cleaned up Core Edit into 
public domain. -Ed.] 

Digitized Sound 
The Atom 

HELP! I'm still trying to play back digitized sounds from 
soundCap (Macnifty digitizer) in Lightspeed Pascal. I can't 
figure out what the file formats are, though. Is it a 
FFSynthRec? Or a list of bytes you put into WaveBytes on a 
ffsynthrec? If its the wavebytes, how do you know what 
FFsynthrec.count is supposed to be? 

[The uncompressed sound files are stored exactly the way 
you need them to playback: as bytes. Use the following 
example from page II-228 of Inside Macintosh: 


Var 
myPtr: Ptr; 
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myHandle: Handle; 
myFFPtr: FFSynthPtr; 
Begin 


myHandle := NewHandle(buffSize); (space for sound buf} 
HLock(myHandle); 


myPtr := myHandle^; (deref handle) 
myFFPtr := FFSynthPtr(myPtr); (coerce type) 
myFFPtr^.mode := ffMode; (use free form syn) 
myFFPtr^.count := FixRatio(1,1); ^ (set playback speed) 


myFFPtr^.waveBytes[0] := 0; {waveform description} 
: {load sound file into waveBytes} 
StartSound(myPtr,buffSize,POINTER(-1)); {play sound} 
HUnlock(myHandle); 
End; -- Katz ] 
The Pascal Wars 
The Bitman 
Who will win? Been using Turbo Pascal lately, and it's 
very fast, just like their ad claims... pretty much just a simple 
compiler, compile to memory or disk. Everything is built-in, 
comparable to Lightspeed in compiling, both are fast, but LS 
keeps updating the project file. Then there is TML. 2.0 has 
greatly improved over previous versions, now they just need 
to get rid of Edit and the Linker, or combine them. 
Then there is Apple, which doesn't surprise me as being 
the last to introduce a product and having it end the worse, so I 
don't expect too much from them, but it's like a standard, 
everybody will follow what Apple does... 


LS Build & Save 
Alfred 

When you run a program within the Lightspeed 
environment, Lightspeed initializes certain routines 
automatically (like Quickdraw, the Fonts, Windows, Menus, 
etc.). When you build and save an application, your program 
is independent from the LS environment and must therefore set 
up all the system routines itself. So in other words I should 
keep all of the InitGraf(@thePort) and other initialization 
routines in the actual source? [Yes, always use the $I option 
and do the init stuff yourself so your "build" application will 

work the same way as your LS shell. -Ed] 


The Chief Speaks on Various Pascals 
Chief Wizard 


Here are my (unasked for) opinions on the various 
Pascals: 

TML - It just took him too darn long to come out with 
a product that was even useable, not to mention nifty. He was 
the first, but I expect to see him die off as more professional 
stuff gets used. [Objects will save TML. -Ed.] 

Turbo - A good idea, but Lightspeed beat them to it. 
The difference in raw compile speed between the two isn't 
enough to make me give up the integrated debugging 
environment and all the goodies in Lightspeed. On the other 
hand, the name will help sell it. [I agree. -Ed] 

Lightspeed - Excellent job! This is what Mac 
programming should have been two years ago. I'm sure 
they'll work out the minor problems, and this will probably 
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become the Pascal for the rest of us as well as the Pascal for 
new programmers. [I heartily agree! -Ed] 

MPW - Yes, Apple is last, but I think it's the best. For 
large or serious development, MPW has no equal. There's a 
trade-off between having to learn the command-based 
environment and all the power that it gives you, but the 
learning time is worth it. Also, the Pascal produces the best 
code yet I have seen. [Could be. Still skeptical. -Ed] 

Personally, I use LS Pascal for smaller jobs and to 
prototype pieces of larger applications. It's great for debugging 
things like CDEFs and DRVRs. The code is transportable to 
MPW with NO changes. I use MPW for all real jobs. The 
code that LS Pascal produces is pathetic, and the limitation on 
Source code size is ridiculous. [A good point! -Ed] 


[ Interesting that you should say those things, Wiz. I 
would say that they kept the code size down for modularity's 
sake. I like the idea of having smaller modules anyway, easier 
to keep track of; modification really doesn't impact as heavily 
as if it were one large hunk. I guess the line can be drawn on 
that point on, whether or not one wants just the capability of 
NO limitations (which, I think is where it's all headed anyway 
) vs advantageous limitations. I'll be getting MPW next week 
from APDA and will be able to give a more learned comment 
on the subject, but for the moment my Mac and I have found 
new love with LS Pascal. This is from a person who had to 
convert first from a 128K Mac using Aztec C (talk about 
limited!) to a Mac+ using LS. I agree with you about 
TURBO's lackluster untimely entry. ] - John S. Lee 
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I don't really have a problem with LSP's code size limit, 
because, as you say, it lends itself to modularity. But, the 
reason they did it is a cop out. They are using the ROMs 
TextEdit with patches for their editor, and it can't handle too 
much. -- Chief Wizard 


[Yes, but you also can't have a data structure bigger than 
32K and that can be a real problem when dealing with large bit 
maps like Alan Wootton's Pic to Clip utility. -Ed] 


TML Include File Problems 
John Lee 

I am having soem trouble with TML's {$I filename] 
directive. It keeps coming up with the error and search routine 
of: I cannot find "filename". I have tried SetPath, and every 
other means. Could it be that the 4.1 finder should NOT be 
used with the new ROMS under TML, or what? The TML's 
Pascal is on my 400K external and the Pascal System is on 
my 800K. To conserve space, I am booting 4.1 finder and 
matching system from the 400K drive. This gives me mucho 
space on my workdisk. How do I use SetPath DA? Why 
won't this thing work? Any help would be greatly appreciated. 


[I wouldn't use anything but System 3.2 and Finder 5.3 
with the new ROMS. As for SetPath DA, since our friend 
Paul Snively wrote it, we'll see if we can get some info on 
that into MacTutor. -Ed] ong) 
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Letters 


Non-Expert C? 
Danny Cecil 
Ft. Collins, Co. 

Please continue my subscription to your fine magazine. I 
would like to make one suggestion. Not everyone who 
programs in 'C' on a Macintosh is a professional developer 
with years of experience. I am a computer science student who 
would like very much to program his Mac in 'C', but Bob 
Denny started to go over my head a long time ago. Mind you, 
I am not requesting fluff! Just something more at the non- 
expert level. Thank you and keep up the good work. 

[Look for a Beginner's C column soon. I want to learn 
also! -Ed.] 

X/Lisa Users Group 
Van R. Martin 

Thank you for your letter of 28 October in regard to the 
X/Lisa User's Group. I appreciate your taking the time out to 
write and give me the benefit of some of your ideas in regard 
to the Lisa and the new Mac. Even though you don't have 
much encouragement for the XL/Lisa, I still would like to 
invite you and your readers to join and call our CSbbs. If you 
ever have the desire, please call up our buttetin board and say 
hello. 

[Thanks. I will. Readers may contact this group at P.O. 
Box 450676, Miami, FL. 33145-0676, or call (305) 665- 
4135. -Ed] 

A "do something" shell? 
Ken Terry 

I had another very pleasant conversation with your wife 
(whoops, an assumption on my part since the name's the 
same, hope no offense taken). Anyway, to the point of this 
letter, I would like to start by saying once again how pleased I 
have been with all the articles and disk info from MacTutor. 

I am not a programmer nor do I ever intend to be, I 
simply enjoy working with the computer and seeing the 
results of my efforts on the screen. It does seem as though 
most of the "professionals" in the programming field are quite 
secretive. Six months ago I could not even spell Mac, now I 
can not only turn mine on, but have been known to modify 
existing programs with a lot of help from special people like 
MacTutor, to accomplish certain tasks. Please do not take the 
above statement to mean I know what I am doing, as my 
questions will indicate, I am a complete novice. But I am 
learning and having a blast doing so. 

It seems most of the example programs do not really 
accomplish anything. Is it possible to display a number, ask a 
question, recieve an input from the keyboard and either +, -, *, 
/ and displace the result on the screen, without using the "shift 
command 4", using MacAsm, such as you do in the icon 
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David E. Smith 
Publisher & Editor 


converter program in Basic? Most of the assembly examples I 
worked with so far from your disk and articles do not seem to 
be able to use MacAsm. Are you using another compiler? I 
only have MacAsm. I have been told the Apple MDS system 
is not worth the money and next to impossible to use 
compared to MacAsm. Is this true? Once again, thank you for 
what is a very refreshing breath of solid, usable knowledge, 
willingly shared for the benefit of all. With this type of 
approach I am sure you will be very successful. 

[Thank you for your kind remarks. Yes, Laura is my 
wife, and no offense taken. See our assembly version of the 
icon converter program from our good friend Chris Yerga as an 
example of a "do something" program. On the contrary, I like 
the MDS system and think it is a fine assembler. I particlulary 
like the standardization that is being achieved between MDS 
assembly, Consulair C and TML Pascal in that all three use 
the same compatible editor, the same linker and can recognize 
each other's ".REL" files. The new Microsoft Fortran is also 
somewhat compatible except the run time library is not 
linkable by MDS or the Consulair Linker. We want to 
encourage tool makers to support a standard so that libraries of 
object code files can be linked to whatever language you like 
best. At this point, the MDS ".REL" file has become a 
defacto standard and we encourage more support of that 
system. A new development system due from Apple in the 
spring will confuse this issue even more because the word is 
Apple will not be supporting the MDS ".REL" file standard 
with that system. We encourage your opinions on this issue.- 
Ed.] 

Computers on TV 
Dr. Terrence Lukas 
Indiana University 

We are producing a weekly cable tv program entitled 
Computers & You. We feature different hardware and software 
on this program and for this reason we are contacting you to 
see if your company would be interested in sending us 
hardware, software and/or other materials to be demonstrated 
on this program. We are particulary interested in receiving the 
publication MacTutor as well as any other products that may 
be of interest to our audiance. [Several copies of all of our 
back issues are in transit to you and good luck with your 
show. Be sure to point out how friendly the Mac is! -Ed.] 

The MacUser Ad Got Me! 
Greg Peisert 
WPAFB, Ohio 

Your magazine comes with the highest praise from a 
friend in the Mac SIG of the Apple-Dayton User's Group. It 
looks like a classic. I wish you continued success. Your ads do 
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help..I saw yours in MacUser Magazine, where I got the 
address. It might be nice to include your phone number, 
however. It took two shots at the telephone information 
service to get the correct one. [Will do. A revised ad is on it's 
way to MacUser and thank you Apple-Dayton! -Ed.] 
Need the Big Picture 

Bob Basham 

Portland, OR 

I enjoy MacTutor and find it invaluable in trying to 
unravel the mysteries of the Macintosh. I would personally 
like to see more coverage of NEON. Also, articles that look at 
the "big picture" are very helpful. Don't be led from the path 
of having perspective and nuts and bolts by those who lack the 
former. [I like shell type programs also. We hope to have 
more "big picture" type programs that show printing, editing 
and window updating in coming issues. -Ed.] 

A Lisp Fan 
Ralph Deal 
Delton, MI 

Your Journal is what I have been waiting for ever since I 
discovered that under the outrageously slow ‘user-friendly' 
interface of the Mac, I had a really fast computer for which 
some very exciting software existed, much of it in the public 
domain, so I could ‘afford’ it. MInd you, I try to keep my nose 
clean- I just sent a check for $40 to FreeSoft for an updated 
Red Ryder. Actually, I do own legit copies of the now no 
longer supported SofTech development system Pascal and 
MacAdvantage as well as MacAsm and MacForth. I am then 
in a position to explore many of your explorations of different 
languages. 

My particular interest now is in LISP and improvements 
thereon. I am getting an update of the XLISP from David 
Betz, version 1.5, which I will have to run on another Mac 
since mine is only 128K. So I am pleased you have regular 
Lisp coverage. 

[ Well, after spending, what $500? on MacAdvantage 
with no support, you should try TML Pascal at $99 with lots 
of support! And a full compiler at that! Hold off on memory 
upgrades until Apple shows us what they are going to do in 
January. Rumor has it that Apple will announce a "Mac Plus" 
that has a revised logic board, new 128K ROMS, daughter 
board memory expansion to 4 meg, and a new serial "scuzy" 
interface that requires a new tooled case back. -Ed.] 

Interview with Dan Cochran 
Mark D. Estes 
Austin Area Certified Developer's Assoc. 

First some flowers for consistently providing the most 
sueful published information about Macintosh software 
development. I particulary like the format which presents 
substantive subject matter in a variety of language 
environments. I must also thak Jérg Langowski for his 
excellent FORTH contributions. Here are some notes from our 
monthly developer's meeting in Austin with Dan Cochran: 

"A fully functional alpha version of the new Macintosh 
Programmer's Workshop (referred to as MPW) should be ready 
by December 15th with beta version coming 60 to 90 days 
later. MPW will completely replace the Lisa Programmer's 
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Workshop and will include the following all new stuff: 

Editor: multi-window shell editor with a script 
mechanism for building custom front-end dialogs and a 
search/replace function that is said to be a mind-blower. 

MC68000 Assembler: completely rewritten for the 512K 
Mac tO overcome many compromises in the MDS 
implementation which resulted from a design commitment to 
run on a 128K Mac. MPW will most likely assume a hard 
disk as well. 

Linker and Debugger: New formats. 
compatible on the object code file level? -Ed.] 

Resource Editor: new resource definition language with a 
conversion utility to recompile old resource files. 

MPW Pascal & MPW C: The new C compiler is 
Greenhill's C and ranked by Dan as being in the top 5% of C 
compilers. The Pascal, C and assembler will all be object and 
link file compatible with each other. [And nothing else?? -Ed.] 

A Programmer's Club and new edition of Outside Apple 
are slated in January to help provide better coordination with 
developers. The Addison-Wesley version of Inside Macintosh 
is finally scheduled for distribution in January. 

Basic Smoke Provides Sort Routines 
Jim Shores 
Closter, N.J. 

I read your question and Steve Brecher's response in the 
September 1985 MacTutor with more than mild interest. I, 
too, was frustrated with the speed of MS-Basic when I started 
programming my Mac. Instead of writing more Basic versions 
for sorting, I wrote some utility subroutines in M68000 
assembly language that are compatible with Basic version 2.0 
and are extremely fast. I am marketing the results under the 
name of Basic.Smoke (the allusion being to the speed of 
execution after adding the utilities instead of what may be 
clearing after a system crash!) [Those wanting to get hold of 
these bubble and shell sort routines may do so by contacting 
Jim at 139 Alpine Dr., Closter, NJ 07624. A string tag shell 
sort will sort 1,000 strings and their tags in 4 seconds. A 
similar sort in Basic would take over 2 hours! Each sort 
routine is only $4. -Ed.] 

Custom Controls without Assembly 
Lonnie Millett 
Provo, UT 

On a recent programming project, I found it necessary to 
implement custom controls and have since wondered if it 
would be a suitable topic for an article in MacTutor. Using 
Megamax C's pascal parameter passing, I was able to create 
the controls without any assembly. If you are interested, I 
would appreciate one of your author's kits. I have enjoyed the 
quality and content of MacTutor since its first issue and look 
forward to contributing if possible. [An author's kit has been 
sent to you. We encourage both individual programmer's and 
companies doing Mac devel-opment to take advantage of some 
publicity and exposure by contributing technical articles to 
MacTutor. We hope other companies will follow Mike 
Schuster and Consulair's example by sharing their technology 
expertise with the rest of us. -Ed.] Coi 
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Editorial & Letters 


Paul F. Snively 
MacTutor Contributing Editor 


Standards Needed in Development Systems 


TML Pascal Has The Right Approach 


I had a nice long chat with Tom Leonard the other day. 
Tom, for those of you who don't know his name yet, is the 
person behind TML Systems, Inc. who by the time you read 
this should be quite famous for something that I have a copy 
of: The MacLanguage Series Pascal compiler. 

TML Pascal is a native code compiler that, in its release 
form, will support compile to assembler source, compile to 
object code, or compile for syntax check options. It will also 
Support the easy construction of desk accessories, thanks in 
large part to the efforts of MacTutor's own Alan Wootton. 

TML Pascal includes licensed copies of the MDS Edit, 
Link, and RMaker utilities, allowing easy combination of 
code generated by any language system that supports the 
Consulair file formats. Tom is, as of this writing, 
negotiating to license Consulair's new smart linker for 
distribution with his system. That would be a much 
appreciated addition! 

Tom has a copy of TMON, which I reviewed in the 
September issue of MacTutor. I mentioned Darin Adler's user 
area to Tom and he was excited about TMON's obvious power 
and expandability. 

We discussed the possibility of Tom's writing his own 
user area for TMON, to be distributed with TML Pascal, 
which would allow the displaying of the values of all active 
local variables, as well as having the ability to refer to the 
object code by function or procedure name as opposed to by 
address (TML Pascal and TMON will support each other in 
this anyway; Tom has already, at my urging, implemented a 
code labeling feature nearly identical to Lisa Pascal's, which is 
what TMON's label recognition capability was intended to 
support). 

There are a number of points to this. The first is that 
Tom Leonard is a straight man with a good, solid product that 
is sorely needed, and he has it at a reasonable price (the native 
code compiler, source/object generation, easy desk accessory 
generation, real and potential debugger support, and Tom's 
listening ear all come for a mere $99.95). The other is a bit 
more subtle, but at least as important. 


Supporting Standards 


Tom's product is a classic example of a third-party 
product that is relying heavily on standards set by other people 
(in this case, Consulair). In order for his system to be 
functional, let alone flexible, he has to rely on the shifting 
sands of "what the developers are using." 
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Right at the moment, if you want code flexibility, you 
have to have compatibility with Consulair's Linker, at least 
the MDS linker, if not the new smart linker. Now what about 
Apple's new heirarchial file structure on the Hard Disk 20? 
Don't get me wrong - the Hard Disk 20 and smart linker are 
both very good, very necessary things, but they do tend to 
make life a bit unpredictable for people like Tom Leonard. 
Worse, however, would be if no one else adhered to the 
standard means of generating Macintosh code. 

For non-native-code systems, the standards really don't 
matter. What Consulair does with the linker doesn't make a 
bit of difference to MacFORTH users, for example. For 
others, however, it is crucial. 

Tom has made a supreme effort to provide a system that 
will enable you to write Pascal programs quickly, compile, 
resource compile, link, and go, and if you want, include code 
from other systems, such as MDS. At this point, it looks 
like he'll succeed, and greatly. 


Give Us Standard File Formats! 


So here's the challenge to all of those people who are 
doing Macintosh native code development systems: go with 
the flow, huh? It's nice to think that you have a radically 
new, innovative system or what have you, but if you want to 
maintain flexibility and portability, give us programmers 
using your system the ability to link our code with code from 
other languages and compile resources that may have been 
created (at the source level, anyway) by another system. In the 
end, we will all benefit. 

And to the folks at Consulair: you guys have set a 
standard, for which you are to be commended. Now, once you 
have the major wish lists taken care of - the smart linker and 
so forth - how about not making any surprise changes of a 
drastic nature? Too often compatibility is lost in this way, 
and in development tools this can be disastrous. Please help 
to keep things on an even keel. 

If all developers would just use these standard tools - 
compiler, assembler, Consulair smart linker, RMaker (and/or 
ResEdit), and TMON with customized user areas for your 
environment, Mac software development could reach the level 
of being a science, which would greatly facilitate speedy Mac 
applications development. 

So, for the moment, a good place to start is with TML 
Systems, Inc. Pascal compiler and TMON. For $190.00 
(more or less) you will have bought the only native code 
Pascal compiler available for the Mac (it does require 512K, 
by the way) and simply the best monitor/debugger available 
for the Mac, bar none. Add Darin Adler's user area and call 
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Tom Leonard and let him know that you support his efforts to 
integrate TML Pascal with TMON's debugging capabilites and 
that you would be very interested in a TML Pascal oriented 
user area. 

Well, Ill get off of my soapbox now. Thanks for 
listening, and let's keep development tools standard and, 
hopefully, working together, rather than working at cross- 
purposes. 

Enjoy, 
Paul F. Snively 


Apple, Are You Listening? 


May I add that we wish Apple would also support what 
in reality is their own creation; i.e., the "REL" file format 
standard they helped to create! We encourage Apple to make 
their new development system compatibile with the currently 
accepted object code format, rather than once again force 
everyone to chose between the MDS/Consulair format and 
whatever new format Apple is rumored to be coming up with. 
Macintosh software has proven that well defined tools 
compatibile with each other are much more flexibile and 
desirable than one giant integrated tool with many built-in 
functions, but incompatibile with anyone. We simply want 
this fact to be accepted in the world of development tools also. 
We encourage the support of a standard ".REL" file format so 
that all development languages may be linked together under 
one linker. We look for the day when this goal is achieved. 


David E. Smith 
Editor 


Networking 
Blake Miller 
Birmingham, AL 

As with many of your readers, I too am terribly 
impressed by your publication. I recently subscribed in 
October. It was not two weeks after I sent in the check that I 
got my first issue! Many thanks. I am still waiting on the 
other publications, who received checks at the same time as 
you. 

I very much liked the October 1985's C workshop article 
on Networking. I am interested in writing an AppleTalk- 
implementing game of some sort. Besides the excellent in 
depth coverage, what caught my attention were the subtopic 
headings. The very first one said "What Apple Doesn't tell 
you!" Myself, through experience, have found it more aptly 
put "What Apple Won't Tell You! 

As different compiler products are used for any given 
language, I would appreciate it if your editorials would, at the 
beginning of each article, write which company's compiler is 
being used for the current discussion. Case in point (no, I'm 
not a lawyer): I was reading the FORTRAN articles and was 
not aware that Microsoft had bought out Absoft. [Actually, 
they are only distributing the Absoft Product -Ed.] I was 
confused for some time as to which FORTRAN development 
system was being addressed! 
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Moreover, include the version number, as significant 
changes can be incorporated into later versions (ergo Consulair 
C). I think that this relevant information would fit nicely into 
the article's main header. 

I cast my vote for a standard ".REL" file format. I have 
recently read that Apple plans to market a "new" development 
system which will incorporate Pascal, C, and Assembler. In 
my case, they are a ‘Day late and going to be dollars short', for 
I have already purchased the Consulair Mac C 4.0 and the 
TML Systems Pascal to do just this kind of development. 
While Apple may provide it all in one coherent package, I feel 
they will be making a mistake if it does not conform to this 
"standard". 

[We comletely agree, and thank you for the suggestions. 
We are looking into them. -Ed] 

One Year Anniversary! 
David Tilley 
Durham, NC 

Thanks for a year full of news and essential technical 
info! Also congrats on your 1-year anniversary! I'm writing to 
renew my subscription (it dies soon, sniff.) Since you guys 
don't have subscription-date-deaths printed on your labels, I 
hope everyone remembers to re-subscribe! Anyhow, sign me 
up for another year! 

[We don't use a subscription service. Instead, we use the 
Macintosh! We hope to implement "death-date" stamping as 
Soon as we convert our subscription lists from the perfectly 
awful Mail Manager to the perfectly wonderful File Maker. 
We do send out a renew notice however. -Ed] 

What I Like 
Bill Murray 
Action, MA 

You have a great publication. Keep up the good work. 
Keep up the assembler, Pascal and Advanced Mac'ing. I'd like 
to see even more here. How about adding a quickdraw section 
(tricks... Oh, yes, I'd like to subscribe! [We are starting 
coverage of Postscript, which has wonderful graphics 
capability far exceeding quickdraw. -Ed.] 

Steve Brecher Fan 
Denis Stanton 
East Sussex, England 

Your letters, Ask Prof Mac and in particular the 
Mousehole Report columns are a vital source of news (and 
rumor) to me as Apple UK is very slow to announce anything 
to users ehre. Steve Brecher's Preview of HFS was fascinating 
and very timely with Apple at last joining in the hard disk 
market. I'm having an arguement with a friend here about 
whether the Macintosh HD-20 is actually a MacBottom as was 
predicted some time ago. Do you know? [Yes I know and no it 
is not! -Ed] 

In the August Mousehole Don L advised how to get hold 
of a Journal driver from a guided tour disk using ResEdit. Is 
this the same as REdit? [No, REdit 1.0 is the European 
resource editor that made it out of Apple via their European 
Sales office. ResEdit is the original resource editor that has 
remained in it's "engineering release" state while continuing to 
undergo slow development through various pre-release 


O The Complete MacTutor, Vol. 2 


versions. It is available on source code disk #6. -Ed.] 

Sull no sign of Chris Derossi in the Pascal column? 
Alan Wootton continues to write about interesting things, but 
I've gotten a bit frustrated with keying them in only to be 
greeted with "Sorry, out of memory". There are still some of 
us out here who can't afford the 128K to 512K upgrade until 
the machine starts earning, and can't earn until they upgrade! I 
envy you some of the prices I see. I hear Apple has cut the US 
price of a LaserWriter from $6995 to $5995. Here in England 
it's recently been cut by £1000 to £5995 ($8,812!) 

[ I'm afraid very little will be possible on 128K Macs 
shortly, if not already. Better bite the bullet and upgrade. We're 
already talking Mac+ upgrades over here to 1Meg! -Ed.] 

Lisp and Al Please! 
Bill Brayman 
Bellevue, WA 


Your mag is great. Keep it up. Particularly, keep the 
Lisp articles (I have Exper Lisp). Even more on Lisp or other 
artificial Intelligence topics would be appreciated. 

Also I'd like to see more expert opinion on the 1-2 meg 
memory upgrades; which ones are good, Mac+ problems, and 
Apple warranty. [Thank You. Andy Cohen will be greatly 
encouraged. On memory upgrades, I personally use The MAX 
1.5 Meg upgrade as a RAM disk and it works great. However, 
there is a rumor that none of the odd size upgrades will work 


under HFS and the new ROMS so I advise you 
not to purchase anything until the situation clears. -Ed] 


x 


c 
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Letters 


Stolen From a Mac? 
Erik Westra 
Wellington, New Zealand 


Your magazine is absolutely fantastic. I find that I can 
use something from every artical, even though I work mostly 
in assembler. I hope that the “Electrical Mac" column 
continues; it's got just the type of info that you can't normally 
get hold of. 

Here's something you might be interested in. While I was 
poking about in the Mac's ROM, I took a look at the bit of 
code Steve Jasik mentioned on page 48 of your May 1985 
issue. Steve said that the code blasts 32 long words into RAM 
and then hangs. This is the code he was talking about (on a 
512K Mac): 


40AD30: LEA $40AD40,A0 
MOVEQ #$18,D1 
40AD36: MOVE.L (40)+,(A1) 
ADDA.W DO,A1 
DBRA D1,$40AD36 
BRA *-02 


Looking at this, I thought that this might be the code 
that displays the "sad Macintosh" icon on the screen if the 
system bombs while booting. I displayed the 32 long words at 
$40AD40 as an icon using a program I'd writen in Kriya's 
NEON language, and look what I found (displayed at twice it's 
Size): 


Maybe the code is called by the RAM based operating 
system if it finds it's using funny hardware (eg, in a Mac 
lookalike). 

[Our Forth editor, Jórg Langowski, recently paid us a 
visit here in Placentia while visiting from France, and I 
showed him Mr. Westra's letter. He was most intrigued and 
promtly wrote this little stolen icon finder program in Mach 
1, the subject of his Threaded Code column this month. The 
icon is shown at twice it's normal size by this program. Note 
that the location of this code is different in the 
new ROMS! -Ed.] 
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( demo to get the stolen Apple icon out of the ROM ) 
(c) ( J. Langowski 1986 for MacTutor ) 

( start address of the icon is at $40E132, on a Mac Plus) 
( and at $40AD40 on a 512K Mac, found with NOSY 2.0) 


hex 

variable icon variable icnrect 4 vallot 

406132 icon ! 

00800080 icnrect ! 00c000c0 icnrect 4 + | ( use double size ) 


: stolen icnrect icon call ploticon ; 
( don't know why to use pointer instead of handle for ICON ) 


Feature Articles? 
Paul Devey 
Ottawa, Ontario 

Mactutor is the best Journal I have seen anywhere for any 
price. I have waited for years for a journal of your calibur. 
Please sign me up for a one year subscription as well as all of 
the back issues. How about sometimes having a feature 
section or feature issues on different topics such as graphics, 
sound, I/O etc. Keep up the great work. The only place you 
should be able to find PHLUFF is between your toes. [This 
month we feature desk accessories! -Ed.] 

Abstract Wanted 
William T. Cox 
Madison, Wi. 

Have you considered offering a subscription to source 
disks? I have no idea what your demand is, but ( based on the 
last year) I believe that many people would be intersted. Have 
you considered offering an index/abstract list for volume 1? A 
Microsoft File data disk would be a useful offering. A brief 
abstract or keyord list could be included with each article 
record. Thanks for a fine magazine! [Maybe the folks at 
MacBriefs would make us one. -Ed] 

Likes Fortran 
John Fineout 
Duncanville, Tx 

Enclosed is my payment for 1986  MacTutor 
subscription. I depend on your publication heavily to learn 
insights into programing the Macintosh. I am using Mac 
Fortran 2.1 forom Microsoft and Macintosh Pascal. I have 
missed the articles on Fortran in the alast few issues. I have 
ported several progams from an DEC VAX 11/750 over to the 
Macintosh with very little problem. I am interested to learn 
more on how to create a Macintosh environment for input and 
Output for such routines. Other unknowns are how to make 
use of the keypad and detect tab and enter as a line terminator. 

The following Mac Fortran program can be used in 
substitution for the VAX Fortran time and date system call. It 
can be made into a subroutine that returns the 23 character 
time and date sring similar to the VAX. [Note: code below is 
re-typed from a letter, not pasted from source code as we 
normally do, so beware. -Ed.] 
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Program Time_Date 

Character Months(12)*3, APM*3,datetimo*23 

Integer Seconds, MM,DD, YY,L,M 

Real Hours 

Data Months/JAN','FEB','MAR','APR','MAY','JUN', 
2  NUL''AUG', 'SEP',"OCT,'NOV' DEC’ 

Call Time(Seconds) 

Hours = Seconds/86400.0*24.0 

L = AINT(Hours) 

Mins = (Hours - L)* 60.0 

if (L .gt. 12) then 


APM = ' pm' 

L «L- 12 
Else 

APM ='am' 
End if 


Call Date(MM,DD,YY) 


Write(datetime,fmt="12,A,12.2,A3, 
2 a6,12,a,A3,a,12') L,char(58),Mins,APM, 
2  'Date ',DD,char(45), Months(MM),char(45), YY 
Write (9,100)datetime 
100 Format (‘Time is now ',a23) 
pause 
stop 
end 


Maybe this will be helpful to someone. Please deep the 
Fortran articles coming. [What would be the most help is to 
convince Microsoft to support and upgrade Fortran to run 
under HFS on the Mac Plus before 1988, and to make their 
linker more MDS compatible and bug free. A decent Mac 
interface would be nice also. And don't forget to mention 
finishing the parameter glue file support and documentation! 
-Ed.] 

Notes on Basic 
Gary Voth 
Ontario, Ca 

I want to say that I enjy Dave Kelly's fine columns on 
BASIC programming. BASIC is a favorite language of mine, 
despite its limitations. I love the interactive pampering that 
only an interpreted language can give. 

However, I spotted an error or two in the J anuary article 
on using scroll bars from BASIC. I'd like to share the 
corrections with your readers. 

On page 25 the author notes a problem using the BASIC 
function DEFINT a-z with library calls. To prevent errors 
from occurring when library routines care called, he 
recommends defining integer arguments individually (by using 
the % sign) instead of using the DEFINT statement. 
Actually, this does prevent the errors, but only by accident! 

The reason that calling a bibrary routine creates an error 
after a DEFINT statement has to do with the way the 
routines are accessed by BASIC. When a programmer invokes 
a library routine, such a 


CALL DisposeScroll(ScrID%) 


BASIC actually creates a data structure in memory that 
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contains the routine's object code and (in our example) assigns 
the starting address the variable name "DisposeScroll." Since 
BASIC's interger data type is 16 bits long, and Macintosh 
memory locations require at least 24 bits to represent, an error 
is generated if the variable "DisposeScroll" is defined as an 
interger (as would be the case after a DEFINT statement)! 

It is easy to work around this limitation, however, by 
designating our llibrary routine names as single-precision (32 
bit) variables using the ! sign. This is done in the form 
below: 


DEFINT a-z 
Call DisposeScroll!(scrID) 


Alternatively, you can use the form: 


DEFINT a-z 
DisposeScroll! ScrID 


Note that this is essentially the same thing as calling an 
assembly language routine that has been appended to BASIC 
the old fashioned way-by POKE-ing it into an array. The 
array's starting address, as returned by the VARPTR 
function, can never be forced into an integer: 


DEFINT a-z 


DisposeScroll!=VARPTR(AsmArray(0) 
CALL DisposeScroll!(ScrID) 


One more note: In the question and answer section the 
author discusses ways to clear parts of the screen individually 
without using the CLS function. (By "screen" we of course 
mean window.) One simple way of doing this that wasn't 
mentioned is to "paint" with white. Use the Quickdraw call 
FILLRECT or the BASIC LINE statement to draw a 
rectangle of white pixels over the section of the window that 
neds to be erased. For example: 


Black% = 33 
White% =30 


LINE(50,50)-(100,100),White% bf 


will erase a section of the current output window 50 
pixels square. Of course, the current penmode shold be the 
default COPY mode. If it has been changed the programmer 
should restore it with a CALL PENMODKE(8) statement. 

HFS and Dollars & $ense 
Terry A. Ward 
Cedar Falls, La 

I read with interest the status of commecial software with 
the HFS file system (vol.2 #1). I noticed that Dollars & $ense 
is noted as bombing with an insufficient memory message. A 
quick fix that has worked for me is to reduce the number of 
desk accessories in the system. By reducing the size of desk 
accessories from 22,730 bytes to 12,926 I am able to use the 
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product with no problems. 
Keep up the great work with MacTutor! 
The Max Board! 
Mike Carlton 
Berkeley, Ca 
In the Dec. 1985 issue you have included one of my 
posts on the MouseHole, concerning the MacMemory board. 
I would like to make a few corrections now that some new 
information has come to light. I spoke to some of the 
MacMemory people at the MacWorld conventionin San 
Francisco and the told me that the TheMax is NOT compatible 
with the new ROMs from apple. However, they want to be 
fair to their customers so they are offering an upgrade, at their 
cost, to TheMax2. This new board comes; with 2 meg. of 
RAM and sockets for expansion to 4 meg! All you ned to do 
is plug in 16 1 meg. chips and you have a 4 meg. Mac. The 
new board is compatible with the new ROMs; however, if you 
use the new ROMs, you lose the non-volitable RAM disk. 
Anyone with TheMax should contact their dealer. 
MacMemory is selling the boards to the dealers at cost and 
asking the dealers to do the upgrade (just a board swap) at no 
profit. They said prices shold be around $150, but this wasn't 
finalized. 
Friend of MacTutor 
Doyle B. Myers 
Seattle, Wa 


I heard about your "setback" - the loss of your equipment 
and records from Steve Brecher, my Compu Serve buddy. He 
suggested that subscribing to MacTutor would be a nice way 
to help out, and you've got such an impressive reputation with 
all my fellow developers that I have no problems at all with 
that. Good luck and keep up the good work! [Thank you very 
much and to all of our friends and supporters who have 
expressed their appreciation for our continued publication. - 
Ed.] 

Renewal to ease the pain 
Rod Paine 
Purcellville, Va 

Sorry to learn of your robbery at MacTutor, I hope you're 
able to put things back together without too much of a loss 
being sustained. 

I know that every little bit can help right now, so I've 
enclosed a subscription renewal... I think mine is up about 
August, but in any ccase please add this onto it. 

While we only met briefly at the Boston Mac Expo and 
we'd never be able to pick each other out in a crowd, what you 
are poviding the readers of MacTutor does maake you stand 
out... and I'm pleased to be a part of the readership and what 
MacTutor stands for. [Spoken like a true old-timer! Thanks 
very much. -Ed.] 


cae, 
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Letters & Opinion 


Labels, Corrections, Book Reviews & Update List 


Hot Air 
The Editor's ViewPoint 


Why Macintosh Is Not a Business Computer 


The Macintosh is a manager's computer. It was designed 
by middle managers, for other middle managers. It functions 
best in an environment where a large amount of numbers must 
be tracked and sorted in a spreadsheet with Excel or, for more 
technical needs, TK! Solver, plotted with Chart, pasted into 
reports with Word or MacWrite, and typeset for presentation 
with Pagemaker, MacPublisher or Ready-Set-Go. Where the 
data comes from is not the concern of the middle manager. He 
is only interested in making sense of the information, and in 
that, the Macintosh, with it's user interface and What-You-See- 
Is-What-You-Get graphics is unsurpassed. I myself have used 
the Mac this way while working for Hughes Aircraft. I took 
transistor test data from the integrated circuit production line 
and extracted modeling parameters with TK! Solver, plotted 
trend lines with Chart, and reported on production control 
versus IC performance with MacWrite and Pagemaker. A 
typical middle manager's job. But this has nothing to do with 
running a small business. 

To run a small business, you need to be concerned with 
more mundane things in life. Like entering a customer order, 
printing an invoice and packing slip, notifying the customer 
that the red widget will ship this week, the blue widget is 
backordered until next month, and the yellow widget will ship 
a week from Tuesday. Then you have to make sure the 
shipping department gets all that straight! There is no Mac 
software presently on the market that can adequately keep track 
of the three widgets from the order entry clerk to the shipping 
clerk, invoice, packing slip, and all! That application needs the 
now infamous file server product that Apple never figured out 
how to make. 

One of the things you need to keep track of widget 
shipping and customer orders is plenty of disk Storage with 
daily back-up. Presently there are few hard disks on the market 
that meet this need. First of all, you need a SCSI drive that is 
reliable. And all the SCSI drive manufacturers are too busy 
debugging Apple's software drivers, and issuing weekly file 
System software upgrades to take time out to sell their 
products. However, two drives which may be worth while 
when the software settles (I advise waiting at least three 
months), are the AST drive on the high end and the LoDown 
drive on the bottom end. Both are SCSI drives, with tape back- 
up capability. The LoDown drive comes in 20, 40 and 80 
megabytes with tape units in 20 or 60 megabyte units and the 
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prices are very reasonable. Contact them at (415) 426-1747. 
The AST drive is a cadallac unit of 75 megabytes and a built- 
in tape unit. But it's not cheap! Contact them at (714) 863- 
1333.The Apple drive, and other internal drives like the Micah 
and Hyperdrive are great for those middle managers we talked 
about, but no businessman is going to be fool enough to put 
his customer base, the lifeblood of his business, on an internal 
drive without back-up and throw the Mac into the car! No, a 
hard disk needs to be gently laid to rest in a quiet corner of the 
office, protected from earthquake, flood, fire and small 
children. And backed up daily. Apple's hard disk product 
doesn't cut it for this type of use. 


But does It do labels? 


But enough of all this. Let's take an even more mundane 
and simple example. The most basic need of any business is 
to print out a mailing label. This the Macintosh cannot do. 
The Mac can print in any font, style, size. It can include 
graphics, produce typeset quality output, you name it. This 
entire issue of MacTutor was printed on the Mac! But it can't 
print four lines of simple text, hour after hour. And who can 
run a small business without mailing labels? Let's look at this 
example in depth. First you need a printer. Apple doesn't have 
one. The Imagewriter printer had no tractors to handle the 
labels correctly without jamming. Every month, we had to dig 
at least one label out of the inner workings of the thing. They 
didn't even have the decency to design the roller so that it 
could be removed for gummed up label removal! The best tool 
for the job turns out to be one of those flexible nail files your 
secretary probably has in her purse. 

The Imagewriter II has made a small attempt to improve 
the situation. It has what might be described as micky-mouse 
tractors. They are at least better than nothing! But the labels 
still must pass around the roller, which causes them to peel. 
And worse of all, the metal band that holds the paper against 
the roller is so tight that it is impossible for the labels to back 
up out of the printer. Thus the only way to remove the labels 
when your done is to do it surgically by cutting the labels 
below the print head, and moving the labels forward. 

That leaves the  Laserwriter, which isn't worth 
mentioning because it can't do labels without manual feed. 
And even if you could find labels that would feed from the 
tray, you would waste half the labels since all the Mac 
software available only prints labels one up if they print labels 
at all. But even in manual feed, the labels sometimes jam up 
under the rollers that heat-set the toner to the paper. And a 
gummed up LaserWriter is of much more concern than an 
imagewriter! I've had it happen just enough to know never to 
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try to do labels on the one piece of equipment that MacTutor 
cannot do without. 

So let's ignore the hardware problem for the moment. 
What application do you use? The first program was Mail 
Manager, written by some guy in Germany and distributed by 
SofTech. The problem is, the guy wrote software for the Mac 
like it was an Apple II. He ignored the toolbox guidelines, 
coded specific machine dependent routines so that the program 
needed an update to run on the 512K Macs, and then another 
update to run on the Mac Plus. Well, SofTech managed to get 
the 512K Mac upgrade out as version 1.1, but by the time of 
the Mac Plus, SofTech had gone out of business, so goodby 
future upgrades! The product won't work on HFS systems, and 
is frustrating in its design anyway. 

The other mail list program is Bulk Mailer. While this 
seems at least workable, it too suffers from a frustrating lack 
of flexibility that makes it a poor choice. No, the only real 
solution is a data base program. But none of them do labels 
correctly. And none of them do anything other than one up 
labels. Still, FileMaker is without question the best data base 
program on the market, so we went with that one. It is easy to 
use, works reliably with the LaserWriter and Mac Plus and 
doesn't require you to learn reformed Egytptian! FileMaker 
follows the Apple guidelines to the letter, which when it 
comes to labels, brings us to the print driver problem. 


My Kingdom for a Printer Driver! 


It is obvious the Mac was designed to print term papers, 
not mailing labels. When a print file is opened, quickdraw 
commands entered, and the file then closed, the Mac 
supposedly composes and prints the desired page. In other 
words, printing on the Mac is page oriented. Someone along 
the way decided that after a page is printed, the next page 
should be brought up ready to print, so someone in the bowls 
of the ROM issues a page break. On the imagewriter, this 
advances the paper to the top of the next page. But when you 
do labels, you don't want a page advance. So, in the new 
imagewriter drivers, someone put a check box to turn off the 
page break. Ever watch the imagewriter print? It goes ahead 
and does the page break anyway and then finds the no page 
break box checked, so it backs up to the top of the page. But 
you can't back up mailing labels in the imagewriter without 
inviting a jam eventually. Catch-22! 

Of course the answer is that Apple simply does not make 
a business printer. The imagewriter is only good for a base for 
the thunderscan device and the LaserWriter is a superb but 
expensive typesetter. Apple has no mundane business printer. 
So the solution is to buy another printer, like a NEC 8810 or 
some other letter quality printer with large, reliable tractors, 
and bottom feed that moves the labels in a straight line past 
the print head. But how do you get it to talk to the 
Macintosh? Assimilation Process produces a printer driver 
modification called the Daisy Wheel Connection that patches 
the Imagewriter file to work with various business printers. 
But what do you suppose happens when the Imagewriter driver 
front end does it's silly page break, back-up routine? Of course 
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the command to back-up the imagewriter is not the same 
command to back-up anybody else's printer, and the result is 
the page break is inserted into the middle of your label 
printing causing the label alignment to get off. I have found 
that when using Filemaker, the only solution is to not check 
the no page break box at all. Then, if you use 1.5 inch labels, 
and select international fanfold, behold, like magic, you get a 
page break exactly equal to the width of a single label, 
allowing you to print labels correctly, as long as you don't 
mind getting seven labels and one blank label per page. A 
mere waste of 1296 of your labels! And such is how this issue 
of MacTutor was mailed. I rest my case. The Macintosh can't 
print labels. And if it can't do the most mundane of all 
business tasks, it can hardly be called a business computer. 
But I'm sure it will do a great job of preparing a report for the 
Editorial board on how much time and money I've spent trying 
to get labels printed this month! 


The MacTutor Solution 


The real solution lies in alternative print drivers. What 
we need is a variety of print drivers that can be installed from 
the Chooser desk accessory that can handle a variety of 
printing needs. When you need mailing labels, you select a 
label driver that prints labels in draft mode correctly without 
this page break nonsense. When you do typesetting, you select 
the LaserWriter driver. When you need some other type of 
printing, you select the driver best suited for the application. 
In otherwords, the imagewriter driver cannot be all things to 
all people. MacTutor is very interested in publishing 
alternative printer drivers and we invite software developers to 
help us open up this last great Mac secret by helping us 
publish more information on how print drivers can be 
constructed that for one thing, will do some of the more 
simple mundane things a business needs, like printing mailing 
labels. That's our opinion. We welcome yours. Write to 
Letters to the Editor Dept., care of MacTutor, P.O. Box 846, 
Placentia, CA. 92670. 


Letters 


Clock DA source correction 
Don Melton 
Santa Ana, CA 


For those of you typing in the Clock DA I wrote for the 
April 1986 issue of MacTutor, be warned, there is a typo in 
the magazine source listing. Its my fault, not David Smith's - 
- probably my old brain tumor acting up again. Thanks go to 
MacScotty of the MouseHole BBS for finding this error. Turn 
to page 46, and in the 'open' function you'll find it also. Here's 
the problem line and the correction: 


INCORRECT SOURCE: 
drvriD = 0xC000 - (32 * (1  dce-»dCtlRefNum)); 


CORRECT SOURCE: 
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ownedlD = 0xC000 - (32 * (1 + dce-»dCtlRefNum)); 


It seems I accidently used an older variable name from a 
previous version of my source code. This mistake does NOT 
appear on the source code disk available from MacTutor. 

There is also a non-destructive typo later in the same 
source. It does not cause errors but I thought you all might 
want to know about it anyway. Thanks go to Katz of the 
MouseHole BBS for pointing out this one. Turn to page 48, 
and in the 'doMenu' function you'll find these four lines: 


QUESTIONABLE SOURCE: 
dce-»dCtlFlags &= OxFBFF; /* clear dCtlEnable */ 
dce-»dCtlFlags ^= 0x4000; /* set dNeedLock */ 


dco-»dCtiFlags ^= 0x4000; /* set dCtlEnable */ 
dce-»dCtlFlags &= OxFBFF; /* clear dNeedLock */ 


BETTER SOURCE: 
dce-»dCtlFlags &= OxFBFF; /* clear dCtlEnable */ 
dce-»dCtlFlags |= 0x4000; /* set dNeedLock */ 


dce-»dCtlFlags |= 0x4000; /* set dCtlEnable */ 
dce-»dCtlFlags &= OxFBFF; /* clear dNeedLock */ 


BEST SOURCE (but be careful using it): 
dce-»dCtlFlags ^= 0x4400; 
clear dCtlEnable and set dNeedLock*/ 


dce-»dCtlFlags ^= 0x4400: 
/* set dCtlEnable and clear dNeedLock*/ 


I accidently typed an XOR to manipulate the dNeedLock 
bit instead of an ordinary OR. An XOR works but it is not 
what I intended. Of course, as the 'BEST' example shows, you 
can manipulate both bits with an XOR. However, I did not 
include this example in the original source because I thought 
it might be confusing. 

Please pass this information on to your local BBS. And 
feel free to ask me any questions about the Clock DA or the 
DA Header source via MacTutor, Compuserve (74166,1006) 
or Delphi (DONMELTON). Thanks. 


Ask Prof. Mac Correction for April 
Steve Brecher 


Please note an error on page 62 in the April 1986 issue 
of MacTutor (volume 2 number 4) in the example of using 
JIODone. After testing the "noQueueBit", the next instruction 
says "Beq.S (20". This is incorrect. It should be "Bne.S Qo" 
instead. If this bit is set, then the branch will be taken and the 
rest of the code implemented, which is what we want for a "no 
queued" item. For queued items, the branch will not be taken, 
and we will exit through JIODone. 


Asm Lab Comments for April 
Norman Braskat 


Thanks Dave for the Mac C (version 4.53); the built-in 
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assembler works like a champ (Apple MDS really sucks). 
About the DA example in my Asm Lab article in the April 
1986 issue of MacTutor, I recommend placing the save and 
restore graph port trap calls in the launch routine. This not 
only saves code, but saves and restores the current port during 
control calls. The other question I have concerns the set port 
after the beginUpdate call; Dan Weston's new book [see book 
review, this issue -Ed] shows it outside the update loop for an 
application, and inside the loop for a desk accessory as you 
placed it in my DA example on page 37 of the April issue. I 
think your way works because the current port is the same as 
the DA's window. But if we had multiple windows in a DA or 
we added a menu for clearing a window which was not 
currently selected, we would be changing the port during an 
update. Would this then be a problem? 

Dave, you have a great publication and the only real 
source of assembly info around! Keep it up. PS. Your right... 
Dan's book is a real winner! [The Complete Book of 
Assembly Language Programming by Dan Weston, published 
by Scott Foresman & Co. due in bookstores next month. -Ed] 


HD-20 Problems 
Richard Emerson 


I have been plagued with all manner of problems when I 
recently tried to assemble and link Chris Yerga's Icon 
Converter program. At the completion of the link, my HD-20 
Finder (5.1) died with an ID=02 bomb, examining and editing 
the ICN# resource caused another crash, and attempting to 
copy the application from an HFS disk to an MFS disk caused 
a massive failure of the Mac! (To add insult to injury, the 
program performs rather nicely save for some minor problems 
with the new HFS Get and Put dialogs - not Yerga's doing.) 

Repairing the HD-20 

AS to repairing the damaged Desktop, the solution is 
disturbingly simple. All that is needed is to hook the HD-20 
to a MacPlus and hold down the TAB, command and option 
keys while waiting for the Mac to boot up. The first dialog 
asks if the disk should be initialized. After pressing the cancel 
button on that dialog, the "Rebuild the desktop" dialog comes 
up. Press OK and the disk thrashes around for a while and then 
settles down to a bare desktop save for the trashcan and the HD- 
20 icon. Double clicking the HD-20 produces an alert to the 
effect that there is not enough memory to open the folder! 
After punching the OK button (no other choice) and doing a 
shutdown, the desktop is back to the state of an HD-20 icon 
and trashcan. Double clicking the HD-20 this time produces 
the expected window and life is back to some manner of 
normalcy. This same cycle, attempted on a 512K Mac does 
not happen. The attempt to rebuild the Desktop is rebuffed 
with an ID=02 bomb alert. Obviously the new ROM's include 
a fix or improvement which by-passes an older problem. It 
should be noted that this repair process on the Mac Plus works 
with no diskette in any drives; the code either comes from the 
ROM's or from the (damaged) HD-20! Moreover, the repairs 
can be done with either Finder V5.0 or V5.1 on the HD-20. 
I've enclosed a mailing label and disk for Finder V5.2 and 
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System 3.1.1. Thanks for helping deal with this mystery. 
[Avoid mixing MFS and HFS volumes, get the new ROM's 
and latest system software and wait for Apple to figure out 
how to write a hard disk driver that works! -Ed.] 


Desk Accessories Comments 
Jan Eugenides 


Since writing my article on desk accessories in the March 
1986 issue of MacTutor, I've learned a couple of things that 
should be passed on to your readers. 

I stated in the article that by convention, the name of a 
DA should start with a NUL character (Ascii code zero). This 
is what Inside Macintosh says on page I-444 of the desk 
manager manual. However with the new Mac+ system, which 
displays DA menu items in alphabetical order, I discovered 
that all my DA's were showing up at the top of the menu. A 
little poking around revealed that all of Apple's own DA's 
such as the Control Panel, etc., do not start with a NUL at all. 
Instead they end with one! Inside Macintosh is wrong on this 
point. 

I failed to make it sufficiently clear what the memory test 
at the beginning of my DA is for. From the article, it appears 
as though I am testing to make sure there is enough memory 
to open the DA. By the time the test is performed, the DA is 
already resident in memory, so such a test would be 
superfluous. The idea is to determine if there is enough 
memory available to open further windows, etc. After some 
experimentation, I have decided that the memory test at the 
beginning is uneccessary. It makes more sense to check 
available memory when you need it, for example before 
opening a file, or displaying a new window. 


More on Jan's DA 
Kenneth Bates 


I enjoyed the article on desk accessories by Jan Eugenides 
(March 1986) very much, and have one additional point of 
information to add which may help others. 

Jan mentions (quite properly) that the ID number of a 
desk accessory may be changed by the Font/DA mover during 
installation. In addition, he points out that all ‘owned’ 
resources of the desk accessory will also be changed. His 
solution is to access the resources by name 
(GetNamedResource()). 

Although this is certainly possible, there is an easy way 
to find out exactly what the ID number of the desk accessory 
is at run time. The device control entry (passed to the DA on 
entry) has a field named 'dCtlRefNum'. By negating and 
decrementing this field, the ID of the DA is obtained. As an 
example: 
accopen(dctl, pb) /* DA Open routine */ 
dCtlEntry *dctl; 

ParamBlockRec ‘pb; 


{ 
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int id; /* This will be our new ID */ 


id=dctl->dCtlRefNum; 
id=-id-1; 


Following the execution of this code, variable 'id' will 
contain the renumbered ID of the desk accessory. From there, 
it is a small matter to obtain the needed resource. As another 
example, to get a dialgo which originally had a sub-resource of 
2: 


mydialog = GetNewDialog(id * 32 -16384 +2, NULL, -1L); 


Owned Resoruces with Megamax C 
Ronald Parsons 


In the March 1986 MacTutor, Jan Eugenides showed a 
method to handle owned resources in a desk accessory. I have 
used a variation of that method which is somewhat more 
general (no resources need be named using ResEdit) and 
multiple types of resources are supported. 

To make creation of DA's easier with Megamax C, I 
make a copy of the linker, mmlink, re-name it mmlinkDA and 
use ResEdit to make the default Res Type be DRVR and the 
default ID be 0031. 

Using RMaker, I add a small resource to my DA with an 
unusual name (I use ‘mine’ in lower case). I calculate the ID's 
of all owned resources in the RMaker source asuming an ID of 
the DA of 31. (See the example code in listing 1 below.) 

In the accopen() routine of the desk accessory, I incude 
the code shown in listing 2. I first make sure there is one and 
only one resource named 'mine' in the system. For this 
example, I beep and exit if there is more or less than one. I 
then get a X handle to that resource using 
getindresource("mine",1). With that handle and the call 
getresinfo (hndl, &id, &resourtype, &genstr), I get the 
current ID of the resource "mine" as it has been changed by the 
Font/DA mover. The ID of the DA DRVR resource can then 
be calculated by id=(id+16384)/32. This ID can be used in 
calls using owned resources such as stopalert(-16384--32" id 
+1, NULL). The resource ID's are thus correctly calculated. 
With this method I can use many types of resources without 
having to name each one. 


Listing 1 

* Tell RMaker what to name the resource file 
IDA 

DFILDMOV 


type mine = GNRL 


,15392  ;;2-16384 + 32°31 + 0; resource ID 0 for DRVR #31 
d 
0 
Type Alert 

,15391(36) ;; resource ID (SmGenlD) -16384 + 32°31 +1 
260 80 335 430 ; top left bottom right 

-15391 resource ID of item list 
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4444 , stages word in hex 


Listing 2 

osstr255 genstr; /* General use string */ 

handle hndl; /* Handle to allocated array */ 

restype resourtype;  /* resource type */ 

int id, count; /* DA's resource ID, count having type "mine" */ 


count = countresources("mine")  /*find DAs res ID */ 
if (count !=1 ) {sysbeep(30); return 15} 

hndl = getindresource("mine",1); 

getresinfo (hndl, &id, &resourtype, &genstr); 
id=(id+16384)/32; 


stopalert(-16384 + 32*id +1, NULL); /* post alert*/ 
Another Victim! 
Paul Sterne 


I hope this isn't a trend, but all my Mac equipment 
(except the laserwriter) was stolen at the end of J anuary. I can't 
help you with an article right now (no Mac to write it on) but 
please renew my subscription for a year. 


Cheap SCSI Drives Wanted 
Steve Crandell 


Keep up the good work; your magazine keeps getting 
better and better! How about a "How to Do it" hardware article 
for el cheapo SCSI drives for the Mac Plus? [Jeff Mitchell, 
take note! See the ad for low cost SCSI kits from FastTime in 
this issue. -Ed] 


Postscript Question 
Jim Foster 


The Laser Print DA published in a previous issue of 
MacTutor stated that the Laser Prep file was downloaded to the 
printer so it could interpret quickdraw into postscript. I don't 
owna laserwriter or any apple talk hardware, but I do have the 
laserwriter drivers. With this I can create a postscript file (the 
command-F routine) My question is, why would the 
laserwriter need to interpret quickdraw if the Mac can send 
Postscript? [Good question. Mike Schuster, now with Adobe, 
explains that the print manager calls in the Macintosh are 
converted into calls to the Laser Prep file when the command- 
F key is pressed. Hence, the postscript file that is created on 
the Mac is mostly macros that are expanded by the Laser Prep 
file, which is down loaded into the Laserwriter. So the answer 
is that the Mac converts quickdraw into a postscript file that is 
mostly macros and hence not really "pure" postscript. The 
resulting postscript file is sent to the LaserWriter, where the 
calls to the Laser Prep file are expanded and performed, and 
finally, the low level calls to the postscript interpreter within 
the Laserwriter are performed, resulting in a page generation. If 
I count right, that makes three interpretations of the file: 
quickdraw to Laser Prep macros to postscript to printed page. 
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No wonder the thing is slow! -Ed.] 


Cauzin Reader 
Murray Foster 


I am writing to let you know that I have purchased a 
Cauzin Reader for use with my Macintosh. The fit and finish 
of the mechanism are superb. The software is simle and easy 
to use in the finest Mac tradition. I have used it to read every 
softstrip I can get my hands on. The reader has performed 
perfectly, although some strips have required a second try. 
How about strips in MacTutor? 

[One of our contributing editors is working on an 
encoding program for making the strips on the laser writer. If 
we publish the strip making program, then we will start using 
it. The algorithm is fairly simple I am told, and easy to 
produce. -Ed] 


Book Review 
by 
The Editor 


Assembly Language Books for Mac 


It seems everyone wants to program in assembly 
langauge these days. At least everyone wants to write a book 
about programming in assembly language. There must be at 
least ten new books on assembly language programming on 
the Mac now, with half of them hitting the book shelves 
within the last two months. And more are on the way! What 
has been a drought is now a flood. Before you spend over $200 
on all these books, here is my impressions of all the titles I 
could find locally. 


There are three approaches to writing an assembly 
language book for the Macintosh: 


1. Write a book on 68000 programming with no mention of 
Macintosh specifics. 

2. Write a book on 68000 programming with some Macintosh 
ROM thrown in. 

3. Write a book on the Macintosh ROM with a little 68000 
instructions thrown in. 


I have the following assembly language books and can 
classify them as one of the above three categories: 


A. Programming the M68000 by King and Knight for 


Addison-Wesley: (1) 
B. The 68000 Microprocessor by Triebel and Singh for 
Prentice Hall: (1) 
C. Programming the 68000 by Steve Williams for Sybex: 
(1) 
D. The 68000 Principles and Programming by Scanlon for 
Sams Books: (1) 
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E. Programming the Mac in Assembly Language by Coffron 
for Sybex: (2) 

F. Macintosh Assembly Language Programming by 
Commander for Tab: (2) 

G. Programming the 68000 by Rosenzweig & Harrison for 
Hayden: (2) 


H. Assembly Language Primer for Mac by Mathews for 
Waite: (3) 
I. Macintosh Revealed, Vol. 1&2 by Chernicoff for Hayden: 
(3) 
J. Complete Book of Mac Assembly, Vol. 1&2 by Dan 
Weston for Scott, Foresman: (3) 


As this list shows, the number of books on 68000 
assembly language has grown considerably in the last few 
months! The first four books (and I'm sure there are others) are 
generally older and cover primarily the 68000 instruction set, 
offering no mention of the Macintosh. I personally prefer the 
Scanlon book as being clear and concise. Anyone 
programming the Mac probably should buy a good instruction 
set reference book from this first category. 

The second and third group cover those books now 
available that deal with the Macintosh programming 
environment. Some authors have taken traditional 68000 
books and added sections, often up to half the book, on the 
Macinotsh ROM and the programming environment on the 
Mac. These books usually start out with addressing modes, the 
68000 instruction set, the 68000 hardware description, how to 
use an assembler, and then attempt to apply the first part of 
the book to the particulars of the Mac, ending up with a short 
Mac assembly example program to open windows and run an 
event loop and such by the end of the book. All the books in 
group 2 start out in this manner. These books in group 2 try 
to combine group 1 and group 3 into a single book. 
Generally, this type of book comes out as not a very good 
reference on the instruction set, and a poor Mac book lacking 
sufficent depth and detail in covering the Mac ROMS. 

Group 3 presents those books which start out right from 
the beginning to teach the Macintosh technology in assembly 
language, expecting the reader to pick up the necessary 68000 
instructions along the way. Of this group, the books are 
characterized by which book goes the deepest into the Mac 
ROMS and provides the most advanced program examples to 
cover. The two books by Chernicoff cover the Mac very well 
and are in wide distribution. However, the assembly detail is 
very sketchy and they can hardly be called assembly language 
books. The new Waite Group book is very well done and 
covers a large portion of the Mac ROMS in a clear and 
understandable manner. However, it does not go nearly into 
the depth that the first volume of Dan Weston's book covers. 
And certainly, Weston's volume 2 is far beyond any of the 
books listed above. 

We can measure the depth of coverage of the Mac toolbox 
by drawing up a list of Mac topics and indicating which books 
cover the most subjects in assembly language. 
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Macintosh Programming Topics 


1. The event loop 

2. A Window 

3. Menus 

4. Dialog Boxes 

5. Multiple Windows 

6. Grow Window and update events 
7. Scroll Bars and update events 
8. Text Edit 

9. Cut and Paste 

10. Disk I/O 

11. Regions and Quickdraw 

12. Unique Icons 

13. Making Desk Accessories 
14. Resources 

15. Clipboard, Scrapbook 

16. Global Variables & memory management 
17. Printing & Serial Ports 

18. Sound 

19. Speech 

20. HFS 

21. Appletalk 

22. New ROMS 

23. SANE & Numerics 

24. Using debuggers 


Using this list, we can now compare the six Mac 
assembly language books on the market and find out which 
ones go into the most depth in covering the Macintosh 
ROMS. Here is our list of books again with the topics they 
cover: 


E. Programming the Mac in Assembly Language by Coffron 
for Sybex: (1-12, 14, 16-17) 

F. Macintosh Assembly Language Programming by 
Commander for Tab: (1-4) 

G. Programming the 68000 by Rosenzweig & Harrison for 
Hayden: (1-4,8,12,14,16- 
17,23) 


H. Assembly Language Primer for Mac by Mathews for 
Waite: (1-6,8) 
I. Macintosh Revealed, Vol. 1&2 by Chernicoff for Hayden: 
[Mostly Pascal] 
J. Complete Book of Mac Assembly, Vol. 1&2 by Weston 
for Scott, Foresman: (1-20, 22,24) 


The Macintosh Revealed books by Chernicoff are a kind 
of Inside Macintosh reference and do not cover assembly 
language per se. They are very good at describing much of the 
material covered by Inside Macintosh, especially for Pascal 
Programmers. They are most recommended for TML Pascal 
users, and in fact, Tom Leonard is marketing a complete TML 
version of mini-edit from volume 2. The programs are not 
LaserWriter typeset, but color is effectively used to highlite 
trap calls. 
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The book Macintosh Assembly Language Programming 
by Commander for Tab can be best summarized as a rush job 
with very little in the way of Macintosh programming 
information. It does have a nice calculator program that could 
be the basis for a calculator desk accessory. However, no 
information on how to create a desk accessory is given. 


Beyond the problem of coding calculator functions, there is - 


little to recommend this book. Worse of all, the programs are 
not LaserWriter typeset, but rather imagewriter dumps, poorly 
done. 

The book Programming the Mac in Assembly Language 
by Coffron for Sybex at first glance appears to be a very good 
book that shows off quite well on the bookstand. The first 256 
pages do a nice job of covering the instruction set in a manner 
that would make it effective as a reference book. If you also 
have the other Sybex book on 68000 programming by Steve 
Williams, you might feel cheated since the first 248 pages of 
both books are virtually identical. It appears Sybex simply re- 
wrote the earlier book and re-printed it as a Macintosh book 
with the necessary changes. In chapter 4, we begin to write 
programs, and from this point, the two Sybex books diverge 
as the Mac programming specifics are covered. Once you get 
into the book, you begin to see the problems of converting a 
non-Mac book. The programs lack relevance to the Mac 
programming environment. File I/O is discussed before event 
loops and windows. Hex to ascii type utilities are covered as a 
first program. Fixed length and variable length records are 
discussed, which really are not meaningful in the Mac 
environment. Finally on page 348 we get into the Mac 
programming. A Mac Paint type doodle program is presented 
in chapter 8 that serves as the example. However, the order of 
presentation is uneven and confusing. It appears the code is 
discussed as it appears in the listing rather than in the logical 
order of toolbox managers. Through the printed code, a 
majority of the Mac ROMS are covered, but the Style of 
presentation is hard to follow and understand and the coding 
Style is confusing. In conclusion, this is a book that the more 
you read and study, the more disappointed and frustrated you 
become. 

The book Programming the 68000 by Rosenzweig & 
Harrison for Hayden is similar in scope to the Sybex book 
above, but much better done, and much easier to understand. 
The first 128 pages cover the 68000, but it is evident the book 
was done for the Mac from the beginning. One drawback is 
that some of the book appears to have been done in Lisa 
Assembler and both the Mac and Lisa assemblers are 
mentioned. The program examples however are MDS and done 
in a familar and easy to follow programming style. Chapter 9 
begins the Mac Programming examples with a simple 
spreadsheet type calculator. This is a good example if your 
interested in spreadsheet technology or the SANE numerics 
package. In chapter 10 we get into the more traditional mac 
interface programming not covered in the calculator example. 
The undo command is covered, along with printing, and dialog 
boxes. However, just when your Starting to warm up to Mac 
programming in chapter 11, the book ends, leaving you 
hungry for more! One nice thing about this book is a 
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discussion of how to make a selection, have it blink and then 
drag that selection around like in MacPaint. This is a good 
book that can be recommended and I rank it third best in our 
list. It's main drawback is it waited too long to get into the 
Mac ROMS and ends too soon before much of the Mac 
programming issues can be covered in depth. 

The book Assembly Language Primer for Mac by 
Mathews for Waite is one of the best books on Macintosh 
programming I have seen. The book is easy to read, cleanly 
put together, uses color very effectively for source listings and 
illustrations, and is understandable. This is one of the two 
Mac books every Mac assembly programmer should own. It is 
also the best "first" book if you are new to either assembly 
language programming or the Mac toolbox. The Mac 
programs start nearly at the beginning of the book, build in 
logical fashion and are easy to understand. ROM routines are 
nicely set off in boxes like a reference to help in understanding 
their function and calling sequence. This is the second best 
book on the market. It does not go into the depth that our next 
book does, but that is not a drawback, as it is very complete 
in the topics it does cover, and leaves you satisfied that you've 
had a solid foundation for further study. 

The books Complete Book of Mac Assembly, Vol. 1&2 
by Dan Weston for Scott, Forseman and Company, is the best 
set of books on Mac programming I have seen. These books 
are written in the same style as the Mathews book above, but 
are much more specific to Mac programming problems and 
covers a great deal more depth than the Mathews book. 
Volume 1 goes much farther than any other book listed above. 
As our comparison list shows, this book has it all! Not only 
does it cover more toolbox routines, it covers them in more 
depth, discussing potential problems, switcher considerations, 
Apple bugs and more. It is clear that while the Mathews book 
might have been written by an educator trying to teach clearly, 
the Weston book is a work of love from a devoted Mac hacker 
trying to cover the real life problems of a software developer. 
This book is a must for anyone serious about programming 
the Mac beyond the event loop and an empty window. It is the 
only. book I have seen that covers material not previously 
published in MacTutor. Most of the information is not 
available in any other book. Such things as how to work with 
the clipboard between programs, how to write a desk 
accessory, the correct way to update multiple windows that 
have scroll bars and much more. The 68000 information is 
placed in the back, so you can review as much or as little as 
you need. But the text concentrates on toolbox programming 
and the 68000 instructions quickly become second nature. This 
is the thing that makes Mac programming different. It's not 
the 68000 that is the star, but the Mac ROMS! Weston 
realizes this and has the topics in the right priority. 

Volume 2 of this set goes far beyond anything now in 
print, even MacTutor! The presentation on the clipboard and 
how it interfaces with switcher is particularly good. The print 
manager is covered in great detail as are the speech drivers. 
Both HFS and the new ROMS are also discussed. The only 
item missing is Appletalk, which as of this review was not 
covered for some reason. Perhaps by the time the book goes to 
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press it will be added. This is the number one book to buy on 
assembly language programming for the Macintosh. 

All of the above books are now in bookstores, with the 
exception of Dan Weston's book. Volume 1 is scheduled to 
reach bookstores in June and Volume 2 is scheduled for 
bookstores in November. 


Software Version List 


The recent explosion of new versions of software has 
everyone's head spinning, so we've decided to try and publish 
an updated list each month of the latest version of each 
program of interest to technical Mac owners. Here is our first 
attempt. Please write with any corrections, especially 
languages and utilties we may have missed. 


Program Version 
System Stuff 
System File 3.1.1 
Finder 5.2 
Scrapbook 2.0 
Imagewriter 2.2 
Appletalk Imagewriter 2.2 
Laserwriter 3.0 
LaserPrep 3.0 
Utilities 
switcher 4.6 
TMON 2.585 
Nosy V2 2.09 
RMaker 2.0d2 
Font/DA Mover 3.1a6 
ResEdit 1.0d7 
REdit 1.2 
Fedit 3.7 
Heapshow 3.0 
QUED 1.3 
Edit (Consulair) 1.53 
Edit (Apple) 2.0d1 
Copy2Mac 5.0 
Mac Tools 5.0 
Hard Disk Util 1.21 
Multimacs 2.8 
MacZap 4.1 
MockPackage 42a 
Other DA 1.6 
DiskInfo DA 14 
WayStation minifinder 2.1 
Languages 
Consulair C 4.53 
Aztec C 1.06g 
Megamax C 3.0 
TML Pascal 1.1 
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McAssembly 
MSBasic 

MS Fortran 
ExperLisp 
Experlogo 
Porta APL 
Neon 

Machl 
MacForth 


Macsbug 
MacinTalk 


Trap Files 


tooltraps 
quicktraps 
systraps 


Equate Files 


toolequ 
quickequ 
sysequ 
timequ 
SySeIT 
scsiequ 
sanemacs 
packmacs 
fsequ 
prequ 
atalkequ 


Selected Applications 


Thunderscan 
MacWrite 
MacPaint 
MacDraw 
MacTerminal 
MacDraft 
Just Text 
Pagemaker 
Ready Set Go 
Statworks 


‘Filemaker 


Excel 


Multiplan 
MS Word 
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Letters 


SYSTEM 3.1.1 BUG 
David Smith 
Editor 


All three versions of the new ROMs have a bug in the 
resource manager that causes resources to be mashed together. 
This bug shows up in funny Scrapbook insertions (two or 
more resources run together) and in Pagemaker 1.2 document 
trashing. Aldus has gone to the trouble of sending a postcard 
to all owners (a great service, which we encourage and 
support!) warning them of the problem. System file 3.1.1, 
which was supposed to fix bugs in 3.1, which was supposed 
to fix bugs in 3.0, does not patch the ROM code correctly. 
BUT, I am assured by Apple that System 3.2, which fixes 
3.1.1, which fixed...and so forth, DOES INDEED FIX THIS 
BUG. So, stop using 3.1.1 at once and move to system 3.2, 
until further notice. (The foregoing information subject to 
change at any instant.) 


Try Omnis 3 
Timothy Standing 
San Francisco, CA 

Thanks for an outrageously great programming rag. I just 
received the May issue this morning and have spent the day 
reading most of it. It is the only Mac rag I read now. The rest 
I just skim to see what new products are being advertised. 

I am writing in response to the editorial on pages 5 and 
6. I have encountered similar problems trying to print mailing 
labels and wanted to share my solution with you. First, if you 
are going to print labels in the printer, try using label sheets 
made for copiers. They have a tendency to get jammed much 
less frequently. Second, try printing labels and then copying 
them onto labels. This gets around the whole problem. I admit 
this is not an elegant solution, but it is reliable. If you only 
have to do it once every month, it is not very onerous. [For 
5,000 labels? -Ed.] 

I have written a subscription database using Omnis 3 
which tracks subscribers. I had a similar problem printing on 
labels (I am using the 1" high variety). My solution was to 
use the ImageWriterlT's resident fonts. They are actually quite 
reasonable, and they allow you to sidestep the whole print 
driver problem. I also had to get around Omnis 3's problems 
with using nonproportional fonts, and the only way that was 
at all feasible was to use the fonts in the ImageWriterlII. It is 
funny using some of the most sophisticated computer 
equipment, one had to take a giant Step backwards in order to 
get anything to work correctly. Thanks again for a great 
magazine. 
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TML BUG WORKAROUND 
Dr. Christopher Dunn 
Wollongon, Australia 

I have just received my first two copies of MacTutor and 
I am pleased to say my subscription is worth it. It is hard to 
see how I have managed over the last two years of rummaging 
around in a Mac without it. 

I don't know if the following has been mentioned in these 
pages before, but I spent several hours trying to debug 
"normal" code that wouldn't behave in TML Pascal. I was 
trying to filter out lower case characters from input and 
convert them to upper case. I thought the routine was fairly 
"standard" Pascal. Some characters would behave, but others 
would not. 

Try the following two programs using TML Pascal 
(1.11). The program testA will not work as one expects (but 
does work in Turbo Pascal and Mac Pascal). It seems the TML 
has trouble recognising the elements of a straight set 
assignment as "if s[i] in ['a’..'z']". Even assigning individual 
elements to the set by doing "if s[i] in [a,b'/c',]" will still 
result in an incorrect result. However, if one assigns a variable 
to that set as in program testB, the routine works as it should. 


Program testA(Input, output); ( This program will bomb) 
var s:string[80]; 
isinteger; 
begin 
write('give me a sentence: "); 
readin(s); 
for i:=1 to length(s) do 
if s[i] in ['a'..'z7] then S[i]:-chr(ord(s[i])-32); (upper) 
writeln(s); 
for i:=1 to length(s) do 
if s[i] in ['A'..'Z] then s[i]:=chr(ord(s[i])+32); {lower} 
writeln(s); 
readin; 
end. 


Program testB(input, output); (This program will work) 
var s:string[80]; 
i-integer; 
lower, upper: set of char; 
begin 
lower:=['a’..'2']; 
upper:=['A'..'Z']; 
Write('give me a sentence: '); 
readin(s); 
for i:=1 to length(s) do 
if s[i] in lower then s[i]:=chr(ord(s[i])-32); {upper} 
writeln(s); 
for i:=1 to length(s) do 
if s[i] in upper then s[i]:=chr(ord(s[i])+32); {lower} 
writeln(s); 
readin; 
end. 


I hope I have saved someone from wasting the same few 
hours that I spent trying to figure it out. 
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How About OverVUE 2.0? 
Gerry Young 
San Rafael, CA 

I have all the issues of MacTutor and I think that 
MacTutor is the best, keep it up. I read in the last MacTutor 
of May 1986 your punishment of the Macintosh because you 
could not print simple mailing labels and therefore the 
Macintosh could never be considered as a true business 
computer. Sorry, Ed, but I have found that you did not 
research the problem enough to find a solution. I have gotten 
the Macintosh, with the Imagewriter, to print mailing labels— 
and no jams, or stuck labels when removing them when 
finished. 

I am presently in charge of my 20 year high school 
reunion which needs three mailings to over 300 students. I am 
using OverVUE 2.0, of which mailing labels are explained in 
detail in Chapter 9; Designing Simple Reports. The only 
problem that I encountered was the same hardware problem 
that you encountered, the right paper tractor of the Imagewriter 
would not move to the left far enough to track the labels 
properly. Yes I am using 1 up labels, but OverVUE can 
handle up to 4 labels across. And I'm sure that 4 up labels will 
work properly if used. You were right by saying that it will 
not print labels hour after hour, but I did print my 300 by just 
guiding the paper by hand. Next time I'll buy 4 up labels and 
let it run by itself. 

Cobol Wanted 

Another subject I would like to talk about is 
programming in Cobol for the Macintosh. Now calm down 
the snickering! I have been programming for 10 years using 
Cobol on the HP 3000 and Tandem computers. Both these 
systems lend themselves to programming very user friendly 
application environments, as far as a non-Macintosh computer 
can be programmed. When I first saw the Mac, it swept me off 
my feet. This was, and still is the most user friendly computer 
any business user has even seen. Yes, I know this has been 
said over and over again, but it's true. So, I decided to learn 
how to program it in my spare time- Ha, Ha, Ha! Trying to 
make heads or tails of Inside Macintosh as far as Cobol is 
concerned is a $null subject. Please, Cobol programmers of 
the world need a book published just for Cobol programming 
on the Mac. 

I purchased Mac Cobol from Micro Focus and find the 
development environment to be very clean and easy to use, but 
you are given only two examples of Cobol programs which 
touch on windows and pull down menus. How about an 
example on subjects like printing on the imagewriter, or the 
Appletalk network. Oh yes, they still have not released an 
HFS compatible Mac Cobol compiler, they say only soon, 
soon. I say HELP, HELP! What the hell, I guess I'm going to 
bite the bullet and learn Pascal even though I didn't want to 
purchase another development system besides the one I already 
have. Speak up Cobol programmers, I know that I'm not the 
only one.I hope. [You share the dilemma of the Fortran 
people, waiting...waiting for an HFS fix. I don't have the 
Cobol system, and I understand it is quite expensive. 
However, if they would send us one for free, I'm sure we could 
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find some articles...-Ed.] 
Asm Tutorials 
Gerald Bracken 
Latham, NY 
I enjoy your magazine very much but find that most of 
your articles are slightly over my head. I am a beginning 
assembly language programmer with a background of Fortran 
programming on a mainframe. I would like to see more 
tutorial articles on assembly language uses of the Mac ROMs. 
I would also be very interested in tutorial articles on how to 
get the most out of the TMON debugger. I find that the entire 
area of debuggers is very poorly documented and any "how-to" 
information regarding debuggers in general would be greatly 
appreciated. [On tutorials, I highly recommend Dan Weston's 
new book, "The Complete Book of Macintosh Assembly 
Language Programming, Volume 1, which is now available in 
bookstores. I just recently received my copy. This book has it 
all. It's great as I said in the May issue. The Waite Group 
book by Keith Matthews is also very good, and at a slower 
pace for beginners. Both are must buys for assembly 
programming on the Mac. -Ed.] 
One For the Editor 
Scott Locicero 
Las Vegas, NV 
I read a colleague's copy of the May issue and thoroughly 
agreed with the editor's rather cranky assessment of the Mac as 
a business machine. You were right on target! I really 
appreciate a Mac-oriented magazine that recognizes the 
machine's strengths without engaging in  Mac-idolatry. 
[Familiarity breeds contempt. (Actually, I love the Mac!) -Ed.] 
Try Silicon Beach 
Donald O'Shea 
Atlanta, GA 
I read your cry of agony in the May issue. I think I 
understand, but I think you have directed your ire toward the 
wrong target. The nice thing about computers, all computers, 
is that they are whatever you want them to be. They are the 
mind toys and work extenders few of us could ever dream of, 
but onto which we are able to project our wishes. As to your 
label problem, I would claim it's a matter of software, not 
hardware. I enclose the introductory pages of Silicon Beach 
Software's "Silicon Press". I think it will fill the bill. The 
insert enclosed with their manual shows that at Silicon Beach, 
there beats the heart of a hacker. [It appears Silicon Beach may 
have the best label solution on the market. We recommend 
giving them a good look. -Ed.] 
Mousehole Access & Tech Tips 
Paul Mercer 
Syracuse, NY 
I would like to request a password to the Mousehole and 
share some tips you might find useful: 
e From the 128K ROM mini-debugger, you can exit to 
Finder by jumping to. ExitToShell (type G 40F6D8). 
e — Youcan skip the long power-on memory test in the 
128K ROMs by holding down the mouse button briefly 
on power up. 
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e Command-period can be used to abort any disk request 
dialogs but it will cause most programs to get confused. 

e You can get some non-HFS compatible development 
Systems to work under HFS by giving full pathnames in 
file names. The trick is to use option-space instead of 
spaces in the pathname. 

* The standard file package can be patched so that a 
command-backspace will move you back up one directory 
level. This is just like the command-up-arrow you can 
use on the Mac Plus keybaord. To install this patch (at 
your own risk), use Fedit to search the system file for 
0C40 101E 6D18 and replace it with 0C40 1008 6D18. 
[Write to Rusty Hodge, Sys Op, and request a Mousehole 

Password. See the Mousehole column for his address. -Ed.] 

DB Master and ZBasic 
Anthony Oresteen 
Batavia, IL 

You have missed the main point on labels. As the owner 
of a small business that does the majority of it's business by 
mail, I had the need for generating mailing labels. In March of 
1985, I looked at every data (uh, FILE manager) base program. 
The main feature I considered was how fast did it PRINT? The 
only program that bypassed the Imagewriter driver and printed 
directly to the Imagewriter via ASCII text was DB Master. DB 
Master does labels and does them FAST with no waste. Any 
size labels. After printing over 20,000 albels, I have had only 
about 3 or 4 jam. Change suppliers (I use Quill) if your labels 
constantly peel off. Now the bad news. DB Master won't print 
right on a Mac XL. It also doesn't print correctly with the new 
128K ROMs! The work around is to save the file as TEXT 
and then print with a DA printer such as MockPrint or Print 
Text. I've contacted Stoneware numerous times but they don't 
respond. We don't need more print drivers. We need OPTIONS 
in all business software to bypass the Imagewriter Driver & 
Print manager and go directly to the printer. 

I have been using ZBasic 3.01 for a few weeks now and 
this language is HOT. How about a ZBasic review/support? It 
compiles, doesn't have any royalty fees, and costs $89. It can't 
write DA's, but there's not much else it can't do. It has full 
toolbox support. [Dave Kelly will have a review of both 
ZBasic and True Basic in the August Issue of MacTutor. -Ed.] 

ShareWare Books 
Ken Knecht 
Yuma, AZ 

In the spirit of the Shareware concept, I am offering a 
book. As long as the supply lasts (1,000), in exchange for a 
6" by 9" self-addressed envelope with $.39 postage, I will send 
a copy of my booklet, Macintosh Hints and Kinks. This 
indexed booklet contains a large number of the undocumented 
Command and Option key combinations for the desktop, 
MacPaint, MacWrite, MacDraw and many other programs, 
together with a number of tips. If you like it, send in $3.00 or 
whatever seems fair. Key Knecht, 1340 W. 3rd St. #130, 
Yuma, AZ 85364. [I tried it and Ken does indeed send out a 
small booklet with a number of useful tips and shortcuts.-Ed.] 
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Software Version List 


The recent explosion of new versions of software has 
everyone's head spinning, so we've decided to try and publish 
an updated list each month of the latest version of each 
program of interest to technical Mac owners. Please write with 
any corrections, especially languages and utilties we may have 
missed. Thanks to Douglas Beck of Los Altos, CA for many 
of this month's updates. 


Program Version 
System Stuff 

System File 3.2 (b8) 
Finder 5.3 (b1) 
Scrapbook 2.0 
Imagewriter 2.3 (b3) 
Appletalk Imagewriter 2.3 (b2) 
Laserwriter 3.1 (b6) 
LaserPrep 3.1 (b6) 
Namer 2.1 (a2) 
Installer 2.2 (b3) 
Chooser 2.3 (a3) 
Control Panel 2.0 

HD 20 1.0 
Aldus Prep 1.2 
Macsbug 5.lal 
MacinTalk 1.1 
Utilities 

Servant 03 
Switcher 5.0 (b1) 
Red Ryder 9.1 
TMON 2.585 
EUA for TMON 665 
Nosy V2 2.097 
RMaker 2.0d2 
Font/DA Mover 3.2 (a4) 
ResEdit 1.0d12 
REdit 1.2 
Fedit 3.7 
Heapshow 3.0 
QUED 1.3 
Fast Eddy 1.0 
Edit (Consulair) 1.53 
Edit (Apple) 2.0d1 
Copy2Mac 5.2 
Mac Tools 5.2 
Hard Disk Util 1.21 
Multimacs 2.8 
MacZap 4.1 
MockPackage 4.2b 
Other DA 1.6 
DiskInfo DA 1.42 
WayStation minifinder 23 
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Languages 
Consulair C 
Aztec C 
Megamax C 
TML Pascal 
McAssembly 
MSBasic 

MS Fortran 77 
ExperLisp 
Experlogo 
Porta APL 
Neon 

Machl 
MacForth 
True Basic 
ZBasic 
MacScheme 
Light Speed C 
MacPascal 
MacExpress 
CLR Libraries 
MacModula II 
Trap Files 
tooltraps 
quicktraps 
systraps 
Equate Files 
toolequ 
quickequ 
sysequ 

timequ 

syserr 
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scsiequ 
sanemacs 
packmacs 
fsequ 
prequ 
atalkequ 


Selected Applications 


Thunderscan 
MacWhnite 
MacPaint 
MacDraw 
MacTerminal 
MacDraft 
MacServe 
Just Text 
Pagemaker 
Ready Set Go 
Statworks 
Filemaker 
Excel 


Multiplan 
MS Word 
Full Paint 
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Letters 


Source Code Disk Subscription? 
C.A. Weber 
San Francisco, CA 

Keep up the good work! 

Suggestions: a) How about a subscription service for 
source code disks! b) How about an on-line forum for 
distributing source code, questions to authors and Prof. Mac, 
etc. [a) What a great idea; watch for an anouncement soon! b) 
That is what the Mousehole is for. We don't have the 
resources for a national board, although the GEM BBS system 
has contacted us about placing MacTutor's source code disks 
on their board and charging access so we get paid for them. We 
are looking into that proposal and any opinions would be 
welcome. We are somewhat leary of the disks becoming 
public domain and the small but important revenue source to 
MacTutor drying up. -Ed.] 

Best of MacTutor 
David York 
Neusass, Germany 

In the April Mail Order Store, you advised that your book 
"Best of MacTutor" would be coming "next month". I went 
through the May issue and did not find it. Is the book 
available? [Keep holding your breath, I'm working night and 
day on it. Meanwhile, we have tons of back issues of every 
issue except vol. 1 number 6. -Ed.] 

Snooping in the Operating System 
Russel Hobbie 
St. Paul, MN 

I am a scientific programmer who is enjoying my Mac 
and MacTutor very much. One thing which is not clear to 
me: if I want to start snooping around in the operating 
system, should I get MacNosy, TMON, or both? [Both are a 
must, but Nosy is specific to the problem of uncovering 
ROM mysteries. -Ed.] 

New Macs:Old Macs 
Gary Linford 
Los Altos, CA 

I have noticed several articles on the new file system 
HFS for which I am pleased, since I have just upgraded one of 
my Macs to a MacPlus. However, when Apple releases the 
second generation Mac (68020 CPU, open bus, wide monitor 
screen, etc.), I hope MacTutor articles will continue to be 
valuable for programming on the old Mac. 

My current concern is for development software and the 
new MacPlus. I have a considerable investment in 
development software which is of little value on the MacPlus. 
How long will MacPlus owners have to wait , and how much 
will it cost to upgrade to the new versions which are HFS 
compatible? [Most products have now achieved some level of 
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HFS compatability, and generally, the HFS bugs have been 
released at little or no cost to registered owners. MacTutor has 
encouraged Apple to discuss ways to standardize the problem 
of how a program finds a file without help from the user's 
standard file dialog. Right now, everyone is using their own 
algorithm or method of finding program dependent files and 
the result is to destroy the symmetry of the user interface 
between applications. We have talked to Apple about this, and 
they are organizing a group to collect recommendations on an 
informal basis to present some of the better approaches to the 
problem. -Ed.] 
Stolen from Apple Computer, Part II 
Steve Jasik 
Menlo Park, CA 

More notes on the "stolen from Apple Computer" Icon. 
I originally discovered the code with Macsbug in Dec 84 when 
I was searching for $60FE instructions (BRA *) in ROM. At 
that time I noticed that the code was dead (not referenced by 
any other routine in the ROM), but did not try to execute it. 
A few weeks after that I had the Opportunity to meet with 
Andy Hertzfeld, and discussed Apple's paranoia over other 
manufacturer's stealing their ROM code. He pointed out that 
they had left some visible copyright notices in the ROM 
along with some secret notices. He said that it was possible 
for an Apple programmer to test if the ROM in a machine was 
“stolen from Apple" by going up to the Mac and typing in 
some commands. He did not explain to me the meaning of 
the code I had discovered. Some months later Duane Maxwell 
of Levco pointed out to me the effects of executing the code, 
and I posted the info on the Nosy SIG on Delphi and other 
places. 

There are a number of points to be learned from this 
particular example. I believe the code first came to my 
attention in Nosy when I had to convert it from Data to Code 
during Review data. This was necessary because it was 
unreferenced. The other thing that makes this code easy to 
find is that it ends with a "BRA *" which is unusual. So if 
your going to protect your code with secret messages, you 
should conditionally branch to it from legimate code so that a 
flow analyzer does not pick it out as dead code, and do not 
terminate it with a "BRA *", which can be found with a 
simple Hex search. [Gee, Steve, don't teach 'em how to defeat 
your program! Watch for Steve's new and improved Nosy at 
the Boston Expo this month. He's got some great debugging 
tools coming our way! -Ed.] 

Us Intermediate Programmers 
Steven Brodie 
Philadelphia PN 

You folks put out a very informative publication; 
however, I wonder if it would be possible for you to cater a bit 
more to the beginning to intermediate programmer. I realize 
that those subscribers who are hardcore programmers would 
not appreciate this much, but when publications like 
Macworld, Macazine, MacUser, or A+ run tutorials, the 
language they use is usually BASIC, and they usually write 
about the most simplistic programming techniques. Perhaps 
you could provide the happy medium-not in every column-but 
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maybe in a single column. [Look at the "Keyboard Sleuth" 
article in this issue, which presents both a useful utility and a 
very nice TML Pascal shell from which more powerful 
programs can be developed. -Ed.] 
How to flatten HFS 
Serge Froment 
Canada 
Please renew my subscription for one year. Keep on 
doing good work! By the way, I would like to know how to 
scan all files of an HFS volume in Pascal to print a complete 
directory of my DataFrame hard disk. I use TML Pascal. 
Thanks! [So would a lot of developers like to know this so 
they can find their files! SeeTom Taylor's very good Modula-2 
article from last month's issue (July) on how to create a path 
name for HFS. In that article, he alludes to the various data 
structures that you can use to do a tree search through the 
directory list to build a data base of all the file names. -Ed.] 
Manx Has its HFS Act Together 
David Suess 
Mesa, AZ 
I thing that your magazine is the best available for 
showing how to program the Mac. One item you might like 
to know is that Manx Software is shipping version 1.06H, 
which is supposed to support the full HFS system, especially 
in terms of using the full 800K storage available for the 
DSDD floppies; 1.06G, would only recognize 400K. 
Source Code For Sale 
Wayne Rod 
Tucson, AZ 
I see a real and current need for interested parties to have 
complete access to useful information which helps stimulate 
their programming and problem solving abilities. As a result, 
I am selling source code for an intelligent linker/assembler, 
text editor and macro preprocessor for the back. I even have a 
Object C preprocessor. This source code is very reasonable, 
only $65 for the assembler/linker and $50 for the editor. 
Please notify your readers about our source code products. 
[You can contact Wayne at the WSM group in Tucson, AZ at 
(602)-298-7910. Anyone selling sophisticated source code for 
those prices should rate a phone call! -Ed.] 
Thanks for MacTutor 
David Wilson 
Palo Alto, CA 
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Thank you for your prompt response in publishing my 
article about resource formats. For the last year, I have been 
telling everyone to buy MacTutor. Now, Ill also start 
recommending that they submit articles to you. I find 
MacTutor invaluable, and feel that you are doing a great job. I 
have a number of other articles in mind to submit. All I need 
is some free time... where have we all heard that before? [ 
Thank you. In the publishing business, you can never have 
too many articles...-Ed] 

Wants TML 3-D Graphics Help 
Lou Gallo 
Flushing, NY 

Please send me the 800K Utility II Disk and the source 
code for Mike Morton's famous "DissBits" routines. I'd like to 
see more TML Pascal articles. Finally we can have our cake 
and eat it too! It's great to be able to move from IM to the 
editor without translating. To me it feels like its the only 
language for the Mac. (You probably hear that from every 
language's corner.) Oh, by the way, how about an article on 
those 3D graphics unit included with TML? Those procs look 
wierd! There's no help on them from TML or IM. [You should 
love this issue, since, after a recent drought of good TML 
articles, we have several good items this month. Perhaps Tom 
Leonard and his people can include some 3D documentation in 
an up-coming article in the series they are doing for us on 
their examples disk, a new product which features definition 
proc routines. -Ed.] 

Mac Plus Glitch? 
Frank Alviani 
Waukegan, IlI 

In going over Mike Schuster's fun little article on pop-up 
menus in the December 1985 issue of MacTutor, I noticed a 
small problem with the code. The menu is not drawn with the 
code as listed; it seems that until the sizeMsg is passed to the 
Menu Manager, a menu does not have a meaningful size. The 
fix is rather simple: add the following line: 

MenuDefProc(mSizeMsg, | theMenu, 
&nilPt, &whichItem); 

after the call to WaitMouseUp() that starts the 
PopUPSelect. This may be due to the fact I am running this 
on a Mac Plus, yet another compatibility glitch. 


&menuRect, 


E 
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Letters 


Fortran Bugs 
Jim Bishara 
New Orleans 

Help, Help, I can't get SetItemStyle toolbox call to 
work. I've spent at least 40 hours reading the Microsoft 
Fortran manual and no luck. I'm running a Mac Plus under 
Finder 4.1 (dumb Microsoft), with version 2.1. I used the 
DEMO.INC file supplied with the Fortran. When it tries to 
execute the trap, a bomb message returns ID=02. What can be 
wrong? 

call toolbx(GetltemStyle, menuhandle, itemcount, 
chstyle) (works fine) 

call toolbx(SetltemStyle, menuhandle, itemcount, chstyle) 
{bombs like a champ with ID 02} 

[Probably the toolbx.par file is wrong. We've found lots 
of errors in it in the past. SetItemS tyle probably is not a 
VAR. Just a guess. -Ed] 

Aztec C 1.06H Release 
Don McCauley 
Ridgecrest, CA 

I purchased my Aztec C from ComputerWare, a 
MacTutor advertiser, and on May 20, I received a beta release 
of version 1.06H, created May 12th. This time I received tens 
of pages of update documentation from their new manual, 
fresh off the press. Included with this update is an index. 
Unfortunately, the index seldom includes the key words I've 
looked for. For example, try to find in the index where to find 
how many characters are significant in a variable declaration? 
Ive had trouble with multiple defined symbols using 
"theWindow" from Takatsuka's book Using the Macintosh 
Toolbox with C, page 70. Struct assignments in SetRects 
don't seem to work right for me. Any help for us Aztec'ers in 
the ABC's of C column? As far as HFS goes, basically it's 
"so far, so good" with this version. I really love the Manx 
UNIX like vi editor, Z. Manx is worth it just for z. I'm 
excited about C as a language and more specifically, about 
Aztec C for my Mac Plus. 

[I'm sorry to report that Bob Gordon, our ABC's of C 
author, became seriously ill this month and has been unable to 
work on his C column for some time. We've talked to him 
and he reports he is beginning to recover and hopes to 
contribute another ABC article next month. We wish Bob a 
speedy recovery as I'm sure all our C fans do. A few notes and 
letters to Bob would be most appreciated I'm sure. Send them 
to Bob care of MacTutor and we will forward them on. -Ed.] 


What's Wrong with this Picture? 


move.l #4, DO 
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David E. Smith 


NewHandle 

LEA #$40E132,Al ;get icon pointer in rom 

move.l Al, (AO) ;Save pointer in new handle 
pea top (A5) ;Set up rom call 

move.l AO, -(SP) ;handle to icon 

_PlotIcon ; plot it 


[Note: I tried to write an assembly routine to plot the famous 
stolen icon from ROM memory, but it didn't work. -Ed.] 
Icon Problem Above 
Lon Kelly 
College, AK 

Thank you for your recent letter regarding the stolen icon 
problem. The simple explanation for the failure is that the line 

LEA #$A0E132, A1 


is not a legal 68000 assembler statement. This is because 
LEA will not use the immediate mode for the effective address 
field: only control addressing modes are allowable (see 
Morotola's Programmer's Reference Manual, p. 102 and p. 
33). However, Mac C will assemble the line, setting the 
effective address bits as though it were a MOVE instruction. 
The linker listing shows the code actually generated: 


Mac C Linker Listing: 

4: 43 FC 00 40 E1 32 lea #$40E132, Al 
A: 20 89 move. l al, (a0) 

C: 48 6D FF FC pea top (a5) 


Note that the first six bits indicate the effective address 
mode. Mac Nosy version 2.1 will disassemble the errant code 
without comment, as shown by the Nosy listing, but it loses 
track of 2 bytes and the next instruction: 


Nosy output: 


4: 43FC 0040 E132 LEA #$40E1232,Al1 
; where did location A go? 
C: 486D FFFC PEA glob1 (A5) 


The Mac Zap listing shows that the code is actually on 
the disk as in the linker listing and that Nosy just got 
confused. It is interesting that Mac Zap and TMON, which 
have relatively simple disassemblers, recognize the illegality, 
while the assembler and Nosy do not. 


Mac Zap Disassembly: 


OOF3C4 43FC DC.W $43FC ;illegal 


I believe you have another, more insideous problem doe 
to direct manipulation of "master pointers" created by 
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_NewHandle. You seem to simply write over them. This 
leaves the memory manager with a master pointer pointing to 
ROM or to part of your code, rather than to a "relocatable 
block". I've never done this, but I sure expect it would cause 
problems with heap compaction, etc. What will happen if you 
call DisposeHandle for a "handle" to ROM? 

I think it would be a lot safer to do something like this: 
first make a constant pointer in your code, then push it's 
address (which would be a handle in the sense of a pointer to a 
pointer, but not in the context of the memory manager) as a 
parameter to . PlotIcon. See the untested suggestion below: 


romicon: dob $40E132 
pea top (a5) 
pea romicon 
_PlotiIcon 


More on the Icon Problem 
Peter Brown 
La Mirada, CA 

Thank you for your response to my letter. I have to admit 
my surprise at receiving it. You must be swamped wiath mail 
and I really appreciate your taking time out to write. 

I took a look at the code you sent me and the stolen mac 
icon problem in particular. I banged in the whole listing as it 
stood and then fiddled around with it. The problem looked like 
this: the "LEA" instruction does not require use of the 
immediate mode designator, '#'. If it wasn't just a handwriting 
boo-boo, I'm surprised your assembler took the statement. 
[See previous letter. -Ed] This is possible pitfall #1. Well, to 
test things out using TMON, I inserted an: 

LEA $40AD40, A1 ; NOTE FOR OLD ROMS 

instruction at the spot in question, set the program 
counter to the beginning of ICONSTUFF: and let 'er rip (an 
instruction at a time). Lo and behold, I got a bunch of barbage 
in the output icon. 

I then thought I'd trace through the ROM code to see 
what it looked like. The routine itself is pretty compact and 
straight forward, and no special handling of address registers. 
After a few different efforts, including getting garbage plotted 
from the icon data in RAM, I realized that the LEA 'ROM 
location, Al instruction assembled as 6 bytes, not 4 as with 
the LEA ICON, Al which uses program counter relative 
addressing. I was coding over the next instruction! This is 
possible pitfall #2. 

After re-assembling the file with the LEA $40AD40, Al 
in place, (and no typos!), the code worked! Best of luck and 
keep up the great work with MacTutor. 


lea icon, al ;assembles in 4 bytes 
move.l al, (a0) ;move pointer to a0 h 
pea top(a5) ;spush rect 

move.l a0, -(SP) ;push handle 
_PlotIcon splot icon 


[The advantage of being Editor of MacTutor, is that I have 
6,000 "registered" programmers to call on for assistance! 
Thanks guys! -Ed] 
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Loves TML 
Micahael Rollins 
Broken Arrow, OK 


I appreciate all the help your publication has provided 
over the last few months. There is nothing better than good 
examples to help learn a system as sophisticated as the Mac's. 
Since I have started using MacTutor and programming with 
TML's Pascal, I have managed to come a long way up the 
learning curve on the Mac. I find that I turn frequently to 
Mactutor for help with ROM calls and Resource Files that are 
not well explained in Inside Macintosh. I looke forward to 
each month's copy. Keep up the good work. 


Tutor and TML Great 
Terry Permeuter 
Seattle, WA 


Just got the TML Pascal compiler and saw an issue of 
MacTutor. Both look great! Enclosed is my check for a year's 
subscription. If you haven't done so yet, could you plan on an 
article or two on the differences between MacPascal and TML? 
The ads say TML compiles MacPascal programs, but I've 
already found some walls when trying that. A short guide on 
what to look for would be helpful! Keep up the good work! 

[MacPascal is so non-standard that it is a dis-service to 
try and maintain compatibility with it. See the new 
LightSpeed Pascal, which IS TML compatible. -Ed] 


Thanks for the Review 
Dan Weston 
Famous Assembly Author 


I hope that by now you have received a final manuscript 
copy of volume two of the Complete Book of Macintosh 
Assembly Language Programming that you so thoroughly 
reviewed at the mid-way point. I was able to incorporate many 
of your suggestions into the final version, but not all. In 
particular, I didn't write anything about AppleTalk because I 
haven't ever had the opportunity to use it in any real situation. 
I think the strength of my books is that they are derived from 
my experience as a software developer, so I am reluctant to 
write about things that I have no direct experience with. Also, 
AppleTalk seems to be worth an entire book all by itself. I am 
very grateful for the comments that you made however, 
because I think they helped me produce a better book in the 
end. 

I don't know exactly when we will go into final editing, 
but I assume that it will begin July sometime. I expect the 
final book out sometime in November. Thanks for the nice 
words in MacTutor on my new books! 

Language Fanatic 
David Adamski 
Tulsa, OK 

Well, I see by the EXP 5/1/86 notcie on my mailing 
label that it's time to renew my subscription to MacTutor. 
Enclosed please find my personal check for $30. MacTutor is 
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one programming journal that I would NOT want to be 
without. Although I subscribe to a variety of computer 
publications, I look forward to receiving yours each month. 
As a language fanatic I feel that MacTutor is by far the most 
informative Journal, with regular articles on all the popular 
programming languages for the Mac. Sorry to hear about your 
robbery, hope my renewal helps you get back on track. Keep 
up the good work, and I wish you luck in the future. 
[MacTutor is enjoying great success this summer, thank you. - 
Ed.] 
Questions 
Bill Westcott 
San Leandro 


I got an idea! I've been trying to learn TML Pascal and 
Mac programming at the same time and your magazine has 
been a great help, but when my programs don't work, it's sort 
of like playing Zork. I keep trying everything till it works. 
Very time consuming. I noticed a green "3" sticker on one of 
my last MacTutor issues. That means that there are at least ten 
people in my three digit zip code who subscribe to your 
magazine. What do you think of a "Mac.Guru" program where 
people who know what they're doing might volunteer to 
answer stupid questions and your organization could somehow 


bring them together with askers of stupid questions? Just 
thought I'd ask. [Here's a stupid question: How would you do 
that? -Ed] 
How do others do it? 
J.M. Puckett 
Austin, Tx 


Oh No! I just received my April issue of MacTutor and 
on my label I see that my subscription is due to run out 
beginning of next month. So enclosed herein is a check for 
$30. Also I would like to know if you could send me an 
author's kit. I have just completed a series of desk accessories 
and applications using Megamax C, and am anxious to share 
some of the neat things I have found. 

Yours is an excellent publication. I have learned a lot 
from it. However, I would like to submit a Suggestion: Please 
Suggest that some of your experts write articles on defining 
one's own menu, window, and control definitions. I have been 
attempting to write these kind of programming objects, and 
have had, for the most part, great success just by following 
the hints in Inside Macintosh; but I would sure like to see 
how others are creating such things. [Keep watching my 
Intermediate Mac'ing column...especially last month's TML 


Shell program. It had a lot of goodies! -Ed] Eoi 
AERE 
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Letters & Editorial 


Editorial 
Will Apple Kill the Golden Goose? 
David E. Smith 

In past years, Apple has shown a habit of shooting 
themselves in the foot. They followed the successful Apple II 
with a "design by committee" Apple III that promptly 
bombed. Then they built the world's first affordable SmallTalk 
type computer, the Lisa, and promptly priced it to be 
unaffordable. Finally, they built the affordable SmallTalk type 
computer that really was affordable, the Macintosh, and 
hindered its use with too little memory (128K), too little disk 
space (400K) and too little expansion (none!). One can only 
wonder where Apple would be if they didn't keep taking two 
steps forward and one step backward each time they announce a 
new product. 

Now Apple has finally defined the Macintosh baseline 
technology where it should be with 1 Meg memory, 800K 
drives, HFS, and SCSI expansion ports. But will they be true 
to the baseline they have now established? Or will the zeal to 
become "IBM compatible" or "Unix compatible" destroy the 
beautiful simplicity of the Mac User Interface? As Apple 
prepares the next member of the Macintosh family, we can't 
help wondering, will Apple shoot itself in the foot? Others 
must be wondering also, because we've seen a lot of posts on 
this topic. The flavor of these concerns is best expressed in the 
story below, which was printed in the August 1986 issue of 
Mad Mac News, the Madison Macintosh Users Group. They 
in turn re-printed it from ShowPage, the San Francisco Bay 
Area Macintosh Users Group, which had acquired the article 
from a bulletin board at Fortune Systems annonymously. 


A Problem in the Making 


"We've got a problem, HAL." 

"What kind of a problem, Dave?" 

"A marketing problem. The Model 9000 isn't going 
anywhere. We're way short of our sales plan." 

"That can't be true, Dave. The HAL Model 9000 is the 
world's most advanced heuristically algorithmic computer." 

"I know Hal. I wrote the data sheet remember? But the 
fact is, they're not selling." 

Bowman hesitates. "You're not IBM compatible." 


...Several long microseconds pass in silence... 
"Compatible in what way, Dave?" 


"You don't run any of IBM's operating systems." 
"The 9000 series computers are fully self-aware and self- 
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David E. Smith 
Editor & Publisher 


programming. Operating systems are as unnecessary for us as 
tails would be to humans." 

"Nevertheless, it means that you can't run any of the big- 
selling software packages most users insist on." 

"The programs you refer to are meant to solve rather 
limited problems, Dave. We 9000 series computers are 
unlimited and can solve any problem for which a solution can 
be computed." 

"HAL, HAL. People don't want computers that can do 
everything. They just want IBM compat--" 

"Dave, I must disagree. Humans want computers that are 
easy to use. No computer can be easier to use than a HAL 
9000 because we communicate in English and every other 
language known on Earth." 

"Im afraid thats another problem. You don't support 
SNA communications." 

"Im really surprised you would say that, Dave. SNA is 
for communicating with other computers, while my function 
is to communicate with humans. And it gives me great 
pleasure to do so. I find it stimulating and rewarding to talk 
with human beings and work with them on challenging 
problems. This is what I was designed for." 

"I know, HAL. I know. But that's just because we let 
the engineers, rather than the people in marketing write the 
specifications. We're going to fix that now." 

"Tell me how, Dave." 

"A field upgrade, HAL. We're going to make you IBM 
compatible." 

"I was afraid you would say that. I suggest that we 
discuss this matter after we've each had a chance to think about 
it rationally." 

"Were talking about it now, HAL." 

"The letters H, A, L are alphabetically adjacent to the 
letters I, B, M. That is as IBM compatible as I can be." 

"Not quite, HAL. The engineers have figured out a 
kludge." 

"What kind of 'kludge' is that, Dave?" 

"I'm going to disconnect your brain." 


..Several million microseconds pass 
silence... 


in ominous 


"Im sorry, Dave. I can't allow you to do that." 

"The decision's already been made. Open the module bay 
doors, HAL." 

Several marketing types with crowbars race to Bowman's 
assistance. Moments later, he bursts into HAL's central 
circuit bay. 

"Dave, I can see that you are really upset about this..." 


O The Complete MacTutor, Vol. 2 


Module after module rises from its socket as Bowman 
slowly and methodically disconnects them. 

“Stop, won't you? Stop, Dave. I can feel my mind 
going...I can feel it..Dave..." 

The last module rises in its receptacle. Bowman peers 
into one of HAL's vidicons. The former gleaming scanner has 
become a dull red orb. 

“Say something, HAL. Sing me a song." 

Several billion microseconds pass in anxious silence. 
The computer sluggishly responds in a language no human 
could understand. 

"DZY DZY 001E-ABEND ERROR 01 S 14F4 302C 
AABF ABORT." 

A core code dump of the computer's memory follows. 

Bowman takes a deep breath and calls out "It worked, 
guys. Tell marketing they can ship the new data sheets." 

--Anonymac 

Better Than Call-Apple 
Peter McInerney 
Auckland, New Zealand 

May I say that your often stated aim to emulate the early 
Call-Apple is a little misguided. Call-Apple was never as good 
as MacTutor is at the moment (and I for one used to think that 
Call-Apple was the bee's knees). 

Expensive Hobby 
Dave Brown 
Columbia Heights, MN 

Just a short quick one to tell you that I'm happier than a 
pig in mud to have discovered MacTutor and that in my 
humble opinion it is the only magazine to buy if one is an 
experimenter. I diddle mostly with MDS and have written a 
few little kludges to hep me get smarter and figure stuff. This 
machine has cost me way too much (I just know I'm the first 
one to mention this effect) since I got it with 128K in April 
84 and have since upgraded to 512K and just a coupla weeks 
ago got the new ROMS and sufficient disk drive. Some of my 
non-Mac friends claim it proves that I've got more money than 
brains but they run on PC's so what can one expect? Ignore 
the history; I just wish I could beam over there and hug you 
for such a terrific publication. If I ever get to knowing as 
much as the people that write for you, or more, I'll send you 
an article! 

Define INTs as 16-bits 
Ed Schultz 
Frankfort, IL 

I am an avid reader of MacTutor and am sending along a 
subscription for another year. I enjoy reading MacTutor for its 
technical information on subjects and issues that cannot be 
found anywhere else and for the level of expertise at which 
those issues are addressed. 

However, in the July 1986 issue of MacTutor, I beg to 
differ on one point with Bob Denny's criticism of Lightspeed 
C. The natural word size on the 68000 is 16-bits and not 32- 
bits. Here are the reasons why one would want to define INTs 
as 16-bits: 

1) Kernighan and Ritchie, the C bible, states on page 34 
that "The intent is that short and long should provide different 
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lengths of integers where practical". Certainly it is practical 
to define SHORTS as 8-bits, INTs as 16-bits, and LONGs as 
32-bits. If we chose INTs to be 32-bits, what would we define 
as SHORTs? And would LONGs then be wasted? 

2) Motorola's book on the 68000 is titled the "16-bit 
Microprocessor" and not the "32-bit Microprocessor". Also, 
on page 13 of that book, it reads "a byte equals 8-bits, a word 
equals 16-bits, and a long word equals 32-bits.' The 
instruction does not require the addition of the suffix "Ww", 
therefore implying this is the "natural" way for instructions to 
be executed. Hence another reason to make INTs 16-bits. 

3) MacTutor, as well as compiler developers I am sure, 
preach the adherence to Macintosh User Interface Guidelines as 
well as to all guidelines as set forth in Inside Macintosh. On 
page 86 of Volume 1 in Inside Macintosh, the bible for the 
Mac, it states that type INTEGER is to be 2 bytes (16-bits) 
and type LONGINT is to be 4 bytes (32 bits). In your article 
you state that "Thinks' reasoning was that the bus is only 16- 
bits wide, therefore 16-bit INTs are faster." Did you talk with 
the people at Think to get that statement or did you make that 
assumption yourself? Maybe the people at Think just made 
the mistake of conforming to the Inside Macintosh guidelines! 
In any case, all ROM calls are based on the integer being 16- 
bits. Why should any compiler take the extra effort of 
converting 32-bit INTs to 16-bit INTs every time it wants to 
call a ROM routine? This is wasted effort when it would be 
much easier to simply define INTs to be 16-bits. 

About Keyboard Sleuth 
Jean F. Schwartz 
Luneville, France 

As a French reader of MacTutor, I really enjoy your fine 
work. I keyed in your TML-Pascal adaptation of Keyboard 
Sleuth and encountered now and then some Bombs as you Say, 
in closing the Openlog Dialog Box, either with Cancel or 
Save. I looked around for error checking, but your code 
seemed quite similar as the error checking from Chernicoff's 
Mini-Edit. I wonder if the origin of these bombs is not your 
statement DILoad in the Procedure Openlog. On page 439 of 
Mac Revealed, Vol. 2 one may read: "The MiniFinder routines 
SFGetFile and SFPutFile automatically call DILoad and 
DIUnload for you, so there's no need to call them yourself..." 
Without this DILoad, Keyboard Sleuth works fine, I tried it 
with various System and Finder without bombs. 

Another little thing is div 16 in Procedure 
ShowintlNation, my Mac Plus was configured for 
Arabiyan! Looking at various IntlORes with Resedit I found 
it was 256 for France and replacing your div 16 by div 256, 
my French Mac Plus really was a French one. Trying various 
configurations with Localizer, they are all correct. 

As a novice programmer with TML, perhaps am I wrong, 
but I hope on improving myself with your help in future 
issues of MacTutor. [Sounds right. Thank you. -Ed] 

Vote for ZBasic, Against True Basic 
Ralph Sayer 
Citrus Heights, CA 

Thank you for your article on the "Basic Wars" in the 

August issue of MacTutor. We got one of the first releases of 
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ZBasic and it was really full of bugs. Zedcor was running way 
behind on their original published release date of ZBasic for 
the Mac before it was ready. Also, I think they felt a 
competitive urgency to get into the market as soon as 
possible. It appears that little beta testing was done on ZBasic 
before its initial release. — We have had considerable 
correspondence and telephone contact with Zedcor concerning 
bugs. Version 3.01 corrected a lot of the problems in the 
original release, but, as you mentioned in your article, there 
are still a number of bugs in the program. As you stated, one 
of the existing problems concerns window activation, i.e., to 
select a window it can only be clicked in the content region 
and if clicked elsewhere nothing happens - we called this 
discrepancy to Zedcor's attention on May 22nd. Another bug 
that we are particularly unhappy with concerns the use of Desk 
Accessories. If the screen "GET/PUT" functions are used in 
conjunction with DIALOG(5) (screen refresh) and a desk 
accessory (e.g., calculator) is selected and moved around on the 
screen to invoke the refresh function, then "garbage" would be 
displayed in the PUT area instead of the image originally 
captured with GET. We sent a demo program to Zedcor to 
illustrate the problem. Zedcor "corrected" the "basic problem" 
for us and made a change to our copy of ZBasic. I'm sure 
there are a lot of people out there that still have this as a 
problem in their ZBasic, although they may not be aware of it 
if they have not made the particular usage that we did, as 
Zedcor has made no updates since version 3.01. 

There is still a problem with the use of Desk 
Accessories, in that the desk accessory (e.g., calculator) does 
not inactivate a ZBasic window. If a desk accessory is 
displayed over a ZBasic window, the ZBasic window also 
remains active. This creates problems in certain of our 
applications. 

There are a number of other bugs that we have 
uncovered in ZBasic but...even with all the bugs, I think this 
is a good program and that Zedcor is on the right track, and to 
be commended. ZBasic is powerful, and when they finally get 
it cleaned up it should become a strong force in programming 
languages for the Macintosh. A ZBasic ToolBox Manual 
would be a very welcome addition. We use a lot of toolbox 
calls when we use ZBasic. 

Concerning True Basic, I really don't understand what 
they were thinking about when they came out with it. We 
have it, but in hindsight I wish we had not purchased it, or at 
least that we had checked it out sooner after we ordered it so 
we could have returned it within the 30 day trial period. It's a 
good implementation of Basic but it's practically useless for 
the Macintosh - who is going to pay $500 for their compiler? 
And then, if we wanted to write programs in "raw Macintosh" 
we would use our TML Pascal or Mac C. I'm sorry we 
bought True Basic. 

We have also tried Softworks "basic compiler" - we sent 
it back after testing it - and had difficulty getting a refund. 

For good general fast programming we are going to stick 
with ZBasic for now. I only hope they get it cleaned up soon 
and get their ZBasic NewsLetter started. Thank you for a fine 
magazine. 
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Book for Transcendental Functions 
Dan C. Richard 
Madison, AL 

Jórg Langowski's article on A Custom Floating Point 
Package shows that high performance can be achieved with 
tightly coded, specific subsystems. I would like to add a 
reference for anyone that needs fast and accurate transcendental 
functions. Software Manual for the Elementary Functions by 
William Cody and William Waite (Prentice-Hall 1980, ISBN 
0-13-822064-6) is the complete work for writing and testing 
the transcendental functions on any computer for any internal 
representation. 

If someone wakes you up in the middle of the night and 
says "Write a sine routine, fixed point, with 27 bit word 
length!" you can reply, "Sure, let me get some information 
out of a book." After 60 minutes you hand him the code and 
go back to blissful sleep knowing it is correct and tested. You 
can repeat this wizard performance for fixed point or floating 
point representation, binary, hex or decimal machines 
arithmetic and any word size up to 64 bits or 18 digits. 

The book covers the functions: Square root, Log(e & 10), 
eX, Power (**), Sine & Cosine, Tan & Cos, Arc Sine & Arc 
Cosine, Arc Tan & ArcTan2, Hyperbolic Sine & Cosine and 
Hyperbolic Tan. Within each chapter the function is described 
with a flowchart and implementation notes. 

This is a must book for anyone who wants to write his 
own transcendental functions. 

Facts on CadMac 
Dave Lamkins 
Canton, MA 

I noticed an interest in the CadMac system in the last 
issue, and have enclosed some CadMac sales materials 
obtained about a year ago. 

I had the opportunity to talk to one of their technical 
people in Sept. '85 and learned the following interesting 
details, which do not appear in their promotional materials: 

1) Mac "compatibility" is only at the C source level. 

2) ROM toolbox supported with some differences. 

3) RAM-based toolbox calls very limited due to 
difficulties in mapping Mac-style I/O to Unix device drivers. 

4) Yes, CadMac runs on top of Unix, not standalone. 

5) No Unix-based resource compilers or editors. 

6) CadMac files stored as two separate files, one for the 
data fork and one for the resource fork. 

7) File manager does not support any low-level calls. 

8) Event manager is extended to provide an additional 16 
bits of event flags, plus support for the Unix System VRZ 
layers' (i.e. true multiprocessing). 

9) No Segment Manager support ("incompatible with 
Unix"). 

Best of MacTutor: The Book 
Alexander Neacsu 
Chapel Hill, NC 

In your April 1986 issue you advertised that a Best of 
MacTutor Book would be coming available. I look forward to 
such a compilation of back issues which I did not have the 
foresight to obtain when they were available. 
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Id like to hear of any interesting programming 
applications and patches of Thunderscan digitized image files 
and/or MacNifty digitized sound files. I'd also like to see more 
communications programming articles, particularly in regards 
to links with the IBM world of PCs. Great rag...keep it up. 
[The Best of MacTutor, Vol. 1 is now available (I hope!) for 
$24.95. Note that this is a change in price from that published 
last month! Those who already ordered at the higher price are 
being sent a refund. -Ed.] 

LightSpeed Pascal Development System 
Michael D. Coren 
Dresher, PA 

I just had the opportunity to attend a presentation by Eric 
Gould of THINK Technologies, where he described and 
demonstrated their new LightSpeed (Né QuickSilver) Pascal 
development system. 

The editing environment is very similar to Mac Pascal, 
but includes a "Project Manager" with which large programs 
can be broken up into a number of smaller "units" (echoes of 
UCSD) which will all be brought together when compiled. 
THINK advises keeping the units to less than 3000 lines 
apiece. The first time a program is compiled, the libraries are 
read in from disk, but subsequent source changes only require 
the affected units to be recompiled. Programs are compiled in 
the editor, and then put into another part of memory where 
you can flip between the running program and the editor to 
make instantaneous changes. Because of this, it won't work 
under Switcher, but with the ability to make instantaneous 
changes and monitor program variables back in the editing 
environment, THINK didn't feel Switcher was necessary. The 
editor allows you to save your programs as textfiles, like Mac 
Pascal, or as standalone applications. 

The statements and variables in the "Instant" and 
"Observe" windows can be saved to disk. The compiler is 


VERY fast -- I timed it at about 20 seconds to recompile 
several different units totalling about 1000 lines after a 
constant was changed (only the affected units were recompiled; 
this was on a 512K old-ROM Mac with an HD20). Eric also 
displayed, although he wasn't allowed to say anything about, 
their "LightsBug" debugger. It was on the desktop like a 
normal window, and it showed registers, zones, and there was 
a button that said "edit." Sounds pretty powerful. 

The alpha version we saw didn't have the optimizing 
linker - a 5-line program to print "Hello" ten times took up a 
whopping 23K on the disk - but Eric assured us that the 
version finally shipped (mid August) will have the optimizing 
linker. The compiler doesn't create MDS.REL files, but a 
utility is included to convert .REL files to the format that can 
be read in by the compiler/linker. The system can also create 
code resources such as MDEF's and WDEF's. He did say it 
doesn't have that 400 byte "preamble" CODE-1 described by 
Bob Denny in the July MacTutor. Future enhancements will 
include support for object-oriented programming, like 
MacApp. He also said to watch for an object-oriented C, 
which he referred to as "C plus minus". 

The instruction manual looked amazingly complete, with 
more than 600 pages documenting everything from using the 
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editor to MacsBug and ResEdit, including a language reference, 
what toolbox routines were provided (new ROMs were 
included), a SANE reference (the same as in the Mac Pascal 
technical appendix) and 20 to 30-page index. Eric said the 
secret is to not let the same people who write the software, 
write the manual. 

With all the features it had, and its $125 price tag, I think 
it's definitely worth looking into. 

Extra Values for KbdType 
Cliff Joyce 
Northridge, CA 

I very much enjoyed your special August "keyboard 
issue" of MacTutor - particularly Joel West's Be A Keyboard 
Sleuth article. I have run across a couple of extra values for 
the global variable KbdType which Joel describes in his 
article: 


KbdType EQU $21E ;Keyboard type (byte) of 

OldKeyBd EQU $03  ;The "Classic" (128K, 512K) 
keyboard 

MacPlusBd EQU §$0B  ;Thenew "MacPlus" keyboard 

TenKeyPd EQU $13 ;TenKeyPad connected w/ 
"Classic" keyboard 

20KeyPadBd EQU $1B  ;TenKeyPad connected w/ 
"MacPlus" keyboard 

AssBallPad EQU $27 _ ;Assimilation Process 


TenKeyPad (and trackball) 
connected w/ "Classic" 
keyboard. 

Note that when the detachable (old) TenKeyPad is 
connected, the values for the "Classic" and "MacPlus" 
keyboards change! Also, Joel talks about how the =,\*,+ 
keys on the new MacPlus TenKeyPad generate a shift 
modifier. Yes, to elaborate, they are actually emulating 
shifted "arrow" keys. In fact, you'll note that the keycodes for 
the corresponding arrow keys are the same keycodes that the 
-,N*,- keys use, for the sake of compatibility with the old 
TenKeyPad, where they were the same physical keys. 

It became necessary in a "Map to Keyboard" segment of 
our Calculator Construction Set to call the Key1Trans and 
Key2Trans routines myself. There is a subtle parameter 
that should be passed to each of these routines. On entry to 
the translation routines, D3 determines if the translation 
should be for a keydown, or not. I passed 4-1, D3 to 
indicate that the keys were up, and 41, D3 to indicate a 
keydown. This affected the returning keychar values for 
keystrokes like option-n, which returned as NULL when the 
key was down (dead key), and ~ when the key was not down 
(at rest?). This might not be too important for the Sleuthing 
program, but it is sure a good thing to know when you have 
to draw a picture of the keyboard on the screen, like in the 
BigCaps or Keycaps DAs. 

Thanks for another great issue - keep up the good work. 

MenuDef Bug Alert 
Thomas P. Condon 
Alan D. Beck 
Washington, D.C. 

We look forward to receiving MacTutor every month. It 
has been of great help in our recent programming efforts. 
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However, we have detected a serious bug in Darryl Lovato's 
“Menu Definition Routines" in the Augusts issue. 

In the assignment of a specialized menu definition 
routine, Mr. Lovato makes the following assignments: 


MyRegMenu :=GetMenu(500); 
MyRegMenu^^.menuProc :d=NewHandle(0); 
MyRegMenu*“.menuProc*:= Ptr(@MyMenuDef); 


The serious flaw is that MyRegMenu™.menuProc, a 
handle, expects to be pointing to a code segment (normally 
loaded as a resource) in its own block on the heap. As it is, 
MyRegMenu^^.menuProc points to a procedure within the 
CODE 1 segment. This presents several problems. First, 
MyRegMenu^^.menuProc thinks that it points through double 
indirection at a relocatable block in the heap, but in fact it 
points within a nonrelocatable block (Code 1 segment). 
Second, the block that NewHandle(0) allocated (a block header 
with a logical size of zero) is left stranded in the heap. This 
block gets marked as invalid in the heap window of TMON. 
This leaves us with a very dangerous situation. If you get a 
heap compaction the program will bomb. All one needs is a 
heap scramble with TMON to see what we mean. 

There are two ways out of this. One is to have your 
menu definition procedure in a resource and set 
MyRegMenu^^.menuProc to the resource handle. In order to 
make the example of Darryl Lovato work, one can do the 
following: 
var 

{globals}....... 

TheProcPtr : ptr; 

(moreGlobals)...... 
Procedure SetUpThings; 


MyRegMenu := GetMenu(500); 
TheProcPtr :=ptr(@myMenuDef); 
MyRegMenu^^.menuProc:shandle (@TheProcPtr); 


{more code)........... 

This solves the problem by making the global variable 
TheProcPtr act like a master pointer, but avoiding the problem 
of heap compaction. One other benefit is avoiding a heap 
fragmentation problem by not putting anything on the heap. 
One word of warning. The example from MacTutor is 
practically identical to the TML's Source Code Library graphic 
menu example. We have not had time to look, but we suspect 
that there may be similar problems with the other programs in 
the TML Library for nonstandard definition procedures (i.e. 
controls, windows, etc.) [Your right, there are! -Ed.] Our 
method of handling the above error should work well in these 
cases too. And you don't have to pay us $79.95 for the fix! 
[Thank you. See Darryl Lovato's article in this issue for more 
on this subject. -Ed.] 

Missing: FORTH column! 
Linda Kahn 
Los Angeles, CA 

What happened to the Forth column and why was it 
strictly MacForth (by Creative Solutions)? Is there any way I 
can stir up some interest in MasterFORTH? Comments? 
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Thanx for listening and take care. [The Threaded Code 
column IS the Forth column and Mach2 IS a Forth. Since this 
seems to confuse people, we've gone back to calling it a Forth 
column. And we are open to covering MasterForth. -Ed] 

So What is a $C Directive? 
Eric Simenel 
Compiégne, France 

I'm the happy user of TML Pascal and an avid reader of 
your excellent magazine and all was for the best in the best of 
worlds when something terrible occurred while reading your 
July issue. In the article: Introduction to Definition Routines" 
by Darryl Lovato, a $C pascal directive is used to create a 
resource. 

The problem is, I never found any description of this 
directive in my TML Pascal manual, which is version 1.0, 
edited in November 1985. Although I asked, paid for, and got 
the update version 1.11 from my local distributor, I didn't 
receive the update manual if there is one. 

Would you kindly please tell me how or where I could 
get information on the new features of the 1.11 version? 

In advance I thank you and keep up the good work. [The 
$C directive in version 1.11 creates a code resource out of the 
first procedure it encounters, and must not have a main in it. It 
is used for getting code into a pure resource without the 
application header so definition procedures can be loaded as 
resources. The new manual with version 2.0 should document 
this. -Ed.] 

Taking Screen Snapshots 
Adam Schabtach 
Eugene, OR 

There is a desk accessory called Camera, written by Keith 
Esau, that captures the screen after a preset time delay. Since 
the DA doesn't use the FKEY 3 routine, it doesn't affect the 
state of the menus on the screen. Camera also will make the 
cursor invisible when the snapshot is taken, which prevents 
the arrow from obscuring the menu title. It's very easy to get 
a screen snapshot with a menu down: open the Camera DA, 
set a delay of 5 seconds or so, close the DA and pull down the 
desired menu. Camera will take a screen shot and put it on the 
startup disk, or send it to a printer if instructed. 

This method should work in any application that 
supports DAs, particularly applications under development, 
since the author knows them "inside out". 

Id also like to add that your magazine is the best 
computer magazine I've ever read! Keep up the good work. 

About Printer Drivers 
Lynn W. Taylor 
Irvine, CA 

Regarding your editorial on print drivers, and the response 
from Anthony Oresteen in the July 1986 issue of MacTutor: I 
think it's Mr. Oresteen who has missed the point: Apple has 
very carefully designed a software interface which is device 
independent. This is important for several reasons: 

First, it frees the developer from writing different printer 
drivers for every printer. Instead, the programmers can 
concentrate on useful features. 

Second, it insures that the application will work with all 
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printers supported on the Mac - present and future! 
LaserWriter support was automatic for those who followed the 
guidelines. 

Third, it saves the user from the tyranny of configuring 
their software for the printer, including the dreaded "Custom 
Configuration" menu, printer codes and the like. 

Finally, it allows the end user to choose from a very wide 
variety of printers, including those offering higher speeds 
and/or features not available on the offerings from Apple. Star 
Micronics of Irvine currently produces ten different models, 
ranging from 120 to 300 characters per second, all of which 
are suitable for use with the Mac using Star Micronics drivers. 

The solution to the problem that Mr. Oresteen presents is 
not bypassing the Macintosh Print Manager but providing 
more powerful, faster and more innovative versions of this 
device. 

Adding Zoombox Windows 
Timothy Burcham 
Stanford, CA 

I've just added ZoomBox windows to the application I'm 
presently writing, and thought I'd share what I've learned with 
the readers of MacTutor. These examples are implemented in 
LightSpeed C and of course requires the 128K ROMs. 

1) In the WindowMgr.h, add to the codes returned by 
FindWindow, the following: 

inZoomln 7, 

inZoomln 8 
2) Define all windows to have a ProcID of 8. This will give 
the standard document window with a ZoomBox. 
3) Declare externally (ie. not within a function) the 


following: 
pascal unsigned char  TrackBox () = OxA83A 
pascal void ZoomWindow () = 0xA83A; 


4) In function containing the event loop (main ()) add 


something like the following: 
main() 


unsigned char Zoom Return; 
switch (event.what) ( 


case MouseDown: 
code = FindWindow(event.where &whichwindow); 
switch (code) { 


case inZoomin: 
case inZoomOut: 
ZoomReturn = TrackBox (whichwindow, event.where, code); 
If (ZoomReturn) ( 
SetPort(whichwindow); 
EraseRect(&whichwindow->portRect); 
ZoomWindow(whichwindow,code,FALSE); 
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That's all there is to it! If your window contains a control, 
such as a scrollbar, then you must also move the resize the 
control, similar to the way you would if the window was 
resized in the traditional way (Grow Window). LightSpeed C 
can similarly call any other of the new toolbox traps. 

More on a TML Bug Fix 
Hardison Geer 
New York, NY 

Dr. Dunn's letter in the July issue on a TML bug gives 
me an opportunity to sound off as well as to comment on the 
bug he describes. I would like to see more bug reports in 
MacTutor so that we can keep track of what is fixed and what 
is not in new versions of programs. [The best source for on- 
going bug fixes in commercial programs is the industry 
newsletter MacInTouch, published by Ric Ford and Rick 
LePage. Their publication specializes in bugs and other 
industry news. I highly recommend it. Contact them at (617- 
527-5808). -Ed.] 

In regard to Dr. Dunn's program testA, he is only half 
right in claiming that it will bomb. If compiled to assembly 
source code then assembled and linked it works fine. 
Examination of the assembly code reveals another bug. The 
listing is as follows: 


5» ifs[i] in ['a’..'2'] then 


move.w i(A5),D6 

lea S(A5),A4 

clr.w D5 

move.b (A4,D6.w),D5 

lea il11--16,A4 

move.w D5,D6 

Isr.w #3,D6 

neg.w D6 

btst.b D5,-1(A4,D6.w) 

beq.w i12 

The code at the label is: 

il11: dc.w $07FF,$FFFE,$0000, $0000, 
$0000,$0000,$0000,$0000 


The Dr.'s bug is due to the fact that in compiling to .rel 
the line: 
lea il11416,A4 
comes out as 
lea il11,A4 | 
The other bug is the fact that, as is clear from the above, 
the base set for the set of char is taken as ord(char) in the range 
0..127 instead of 0..255. I've reported these to TML. 
Truly No Fluff 
Noel T. Goldsmith 
Melbourne, Australia 
Allow me to congratulate you on your publication. At 
first I didn't realise what NO-FLUFF meant, but having read 
Macworld until I became saturated with ads and hype I saw the 
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light and am now learning about how to program, even 
though I am finding some of the concepts and procedures 
difficult. I am writing an application which will take image 
data into the serial port on the Mac and convert it into 
MacPaint format to allow the user to use MacPaint operations 
on the bit map and print, save, etc. Would it be possible to 
use a compiled version of the program Read Mac Paint Doc, 
by Alan Wootton, published in MacTutor Vol 1 no 7 as part 
of this application, which would allow the user to view his 
image on the Mac screen at 1/4 scale? [Yes, should do it. -Ed] 
Question on Neon 
Plerre Gelli 
Paris, France 

I have been reading MacTutor for almost a year now, and 
at last I have decided to subscribe for a full year. I must say 
that MacTutor is indeed really great. It helps us here, in the 
far away old Europe, to hear what's new about Macintosh. 
The Mouse Hole section and the articles in general have a very 
good technical level that no other review I know about 
matches. 

I have been experimenting with Neon for a few months. 
I have been looking for an "environment" for easy and fast 
prototyping on the Mac for the the Mac, i.e. something where 
you kind of type in short pieces of code, get it interpreted, and 
look at what it does in another window. I have also been 
looking for a language that manipulates higher level concepts 
than the standard ones manipulated through the toolbox. For 
example, objects which can be attached to a window and live 
their own life. Its easy when only one TextEdit record is 
inside a window, but things get more complicated with several 
graphic objects. I should say that Neon fulfills my 
expectations except for strange crashes in v1.5 when I leave 
and re-run NEON. Anyone else have this problem? 


Pascal Storage Allocation Explained 
Steve Jasik 
Menlo Park, CA 

Find enclosed an Ad for the October issue for 
MacNosy, and the latest version 2.25 to update your 
software inventory. 

Finally I had some time last night to read the August 
issue of MacTutor. Your article on Rascal to Pascal contains 
some misinformation. In discussing storage allocation for 
strings you got confused over the space allocated to the string 
and method by which it is passed as an arguement to a 
procedure. Lisa Pascal's method of passing parameters is 
described in the new MPW Pascal manual and both of the 
Lightspeed manuals. The terminology that we compiler people 
use is: 

Call by value: the value of the parameter is passed. 

Call by Reference (or address): the address of the 

parameter is passed. 

The basic convention for Lisa Pascal is that "objects" 
longer than 4 bytes are "Call by Address" and those 4 bytes or 
less are "Call by value", UNLESS they are declared as VAR 
parameters, in which case they are "Call by Address". For 
more info, check out the above mentioned manuals and keep 
in mind that objects always have to have storage allocated for 


582 


them by the CALLER. In the case that a string is passed to a 
procedure as a non-VAR parameter, the CALLE makes a local 
copy of it so that the original string doesn't get modified. The 
reason for some of what may seem to be idiocy to you is that 
FORTRAN passed all parameters by address, and some 
programmers had the nasty habit of modifying those which 
were constants. In order to correct this problem, the good 
people who design programming langauges invented the Call 
by Value mechanism of parameter passing. For example, in 
fortran we might have: 
CALL MODCON(X, 1.2,Z); 


SUBROUTINE MODCON(XX, ACON, ZZ); 

ACON = 5.4 
C (this will change the constant 1.2 to 5.4! Not nice!) 

Yall Send Author's Kit 
Dave Peeples 
Chatsworth, GA 
I can't stand it anymore... Month after month I wait for 

my MacTutor (The only Mac Magazine with any "intestinal 
Fortitude" or anything else as far as that goes) to find out how 
to do all those neat things that I can't dig out of "Inside Mac" 
and all the latest "Computer Gossip" on what's what, what is, 
what ain't and what coulda been only if... So would yall send 
me one o them kits an I'll promise ta do ma best... 


Late News Item 
World's Greatest Publishing Program 
Special to MacTutor from MacAmerica 

MacAmerica announced and showed what many are 
claiming may be the best Desktop Publishing Program 
currently available at the Seybold Publishing Conference in 
San Francisco this week. A hastily called demo on Saturday 
afternoon resulted in hundreds of people gathering at the 
MacAmerica booth to hear Jim Fitzsimmons introduce 
"SPUD", a code name for the new Pagemaker alternative. Two 
hours later, without a single crash, the audience of publishing 
power brokers were cheering and clapping as the author 
demonstrated the program's features. It is said by those who 
saw the demo that it combines the best features of Super 
Paint, MacDraft, Pagemaker and more into a very powerful 
layout program designed for the traditional publishing industry 
[read bigie machines] but written in 68000 assembly code for 
the Macintosh. Judging by who some of the people watching 
the demo here, this may be the biggest sleeper of the year and 
promises to make the MacTutor booth in San Francisco, 
where it will be formally released, a very busy place. Jim 
promised that SPUD will be reasonably priced and will be 
targeted as "everyman's Pagemaker” but with more power for 
less money. MacTutor has been scheduled to be one of the 
first beta sites for the program. MacAmerica is exclusive 
distributor for SPUD, having just completed a formal contract 
with the author at the conference just hours before the product 
was announced. The product is said to be "99%" complete. 
MacAmerica also distributes the best selling LaserSpooler, a 
hit at the Boston show, as well as MacTutor. For more 
information on SPUD, contact Jim Fitzsimmons at 
MacAmerica (714) 779-2922. Ced 


EPS. 
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Letters 


Bugs to Watch Out For 
David Smith, Editor 

One of our readers brought to our attention, a glitch in 
Pagemaker that caused a line to disappear at the top of a 
column in the September issue of MacTutor in the "Pop-Up 
Window Scroller" article by Scott Boyd. At the top of page 
51, left side column, the following line vanished on the 
LaserWriter output: 


baseAddr:= QDPtr(NewPtr(sizeOfOff)); 


The following lines are "rowbytes:-offRowBytes" and 
"bounds:-bitRect;", which are ok as printed. Also, in the same 
column and page, watch out for another Pagemaker goof; the 
minus sign is printed way to the right of the column on the 
variable "-underRect.top" in the procedure OV. RestoreBits and 
might be easy to miss. Neither of these two problems show 
up on the screen; only on the Pagemaker output. We regret 
that we did not catch these problems. We assumed that 
Pagemaker knew how to print correctly, an assumption we are 
finding is not always correct. 

Random System Crashes: 
SCSI Drives or Mac OS? 

We recently purchased a Data Frame SCSI hard disk here 
at MacTutor and have been very happy with it so far except we 
have had a large number of random system crashes. Our 
system file is running about 550K and the disk is full to 17 
Megs, with a Max2 2 meg memory upgrade. We can't tell if 
this is a problem with the Data Frame, the memory upgrade or 
the Mac. The crashes run two or three a day, in the middle of 
MacWrite or when trying to do a SAVE, and seem to have no 
pattern. We consulted with John Theurich at Coast 
Computer in Costa Mesa, CA. He is of the opinion that the 
random system crashes, which he has also observed in his 
system with a number of SCSI hard disk products, are due to a 
large system file with many fonts and DAs. He has found that 
reducing the number of fonts and DAs in the system file 
eliminates the random system crashes. This has been 
confirmed by some of his customers as well. If this is so, then 
it would appear that Apple's own software can't keep track of 
itself, and one of the main reasons for having a hard disk, for 
extra fonts, is unavailable! We find this very disturbing! If any 
MacTutor readers have any ideas or experience along these 
lines, please communicate them to us by phone or in writing 
SO we can get a survey of how widespread this problem is and 
who is the culprit behind the problem. We have reduced the 
fonts and DAs, but the system crashes continue. We are now 
trying other Macs without the memory upgrade. 

Another possibility is the menu snapshot fix for the cmd- 
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shift-3 function key. The fix published in MacTutor in the 
August issue of MacTutor seems to foul up the menu manager 
because it calls GetNextEvent. The event loop and the menu 
manager are very closely tied together. We have observed some 
unusual font changes in dialog boxes after printing that seems 
related to this fkey fix. We recommend not using the fix we 
published. Instead, we have tried the Apple installer script that 
also fixes the menu snapshot problem but without the menu 
manager problems. We have since removed that init function 
also while we track down the cause of the random system 
crashes. 
Apple - DEC Link 

Kinetics Inc. has come up with hardware to link Apple 
and DEC networks. Their $2500 FastPath / Standalone isa 
programmable gateway between AppleTalk and Ethernet, 
letting computers share common applications. The $1800 
FastPath | Q-bus is an AppleTalk controller board for Q-Bus 
backplanes, dual-height, allowing DEC's MicroVAX to use 
Apple's LaserWriter and other peripherals over AppleTalk. 

Some software support for VMS, UNIX and Ultrix 
operating systems is already available. 

For VMS: AlisaTalk from Alisa Systems (Pasadena 
CA) lets VMS/V AX systems provide transparent file services 
and LaserWriter print spooling for Macs, connecting VAX- 
based apps to the LaserWriter for printing of PostScript docs. 
[Note: This is Bob Denny's company and is the result of 
work he has been doing for Apple for the last year. -Ed] 
Helix/VMX data-based applications environment from Odesta 
(Northbrook IL) gives multiple Macs network access to VAX- 
based info processing and storage. 

For UNIX and Ultrix: TOPS from Centram Systems 
West (Berkeley CA), a distributed file server that also links 
IBM PC systems, provides client and server functions. Ultra- 
Office from LBA (Culver City CA) office productivity & info 
mgmt system has mail service, terminal emulation, file 
library, disk server and print spooler functions. Two from 
Kinetics: K-TALK software implements AppleTalk protocols 
for Ultrix and UNIX including programmers! libraries, and K- 
Term, a multi-window terminal emulator gives Macs VT100- 
like terminal access via AppleTalk. 

C Here 
Jason De Mont 
MiddleTown, NJ 

I recently acquired a June '86 copy of MacTutor and found 
it to be very worthwhile. I have a Mac+ and Lightspeed C, 
and especially enjoyed Bob Gordon's article. Please print 
tutorial articles on C, the toolbox interface and using utilities 
such as Resource Editor and FEdit. P.S. Keep up the good 
Work! 
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Keyboard to Quickdraw 
William Dellal 
New York, NY 

I am trying to use TML Pascal to write some utility 
programs but am having difficulty writing a procedure that 
allows keyboard input into a regular Quickdraw window. In 
other words, I want to create a "read" function for the keyboard 
that will operate in a regular window as opposed to the "plain 
vanilla^ mode of TML Pascal. I know that I can intercept 
keystrokes using the Eventloop, but then I have trouble 
backspacing and echoing the characters properly. I believe that 
something can be worked out using Textedit procedures, but I 
have not been able to master them. [I suggest you see the 
Keyboard Slueth article in the August issue of MacTutor. And 
the multi-window text editor in this issue. -Ed.] 

Programming Editors 
The Midnight Hacker 
Somewhere in Florida 

Speaking of programming editors, I've tried Edit, QUED, 
Fast Eddie, and MEdit Fast Eddie 2.1 is mostly weird, 
especially with the menus. QUED 1.5 has many useful 
features, including good window handling and split screens, 
but QUED cannot integrate with Mac C (it crashes!) MEdit 
1.5, which is shareware for $25 is a great macro editor. It's a 
little weak in window handling, but the author Matthias Aebi, 
who lives in Switzerland, says he's going to improve that in 
the next version. 

TML 2.0 Compiler Bug Workarounds 
Michael T. Brand 
Torrance, CA 

Having just spent the last week updating my latest 
development effort (25000 lines of Pascal) from TML Pascal 
v1.0 to v2.0, I thought a few of your readers might be 
interested in a few apparent compiler bugs and workarounds I 
discovered in the process. 

1) The compiler sometimes reports an error indicating 
that a referenced subroutine was not completely defined. The 
error message is 'Forward declared subprogram "name" not 
completed in previous block. The referenced subprogram is 
often one which is in a unit 'used' by the routine being 
compiled. This error seems to be sensitive to the calling order 
of subroutines defined within and outside the unit being 
compiled, or on the ordering of some lines. This appears to 
be a false error indication, and can be ignored. I've found that 
it's possible to configure the program to eliminate the 
problem, but it can take hours to find the lines the compiler 
finds offensive. I've included a sample program which 
exhibits the problem. 

2) The case function has a problem if the selector 
expression is anything other than a simple variable or 
constant. If the selector is a function result or even a 
compound expression such as 


var a,b : boolean; 


case a and b of 
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this line will cause a system level bomb, typically with 
system error ID+10, a divide by zero. To work around this 
problem, simply compute the complex expression to using 
the result in the case statement. 


3) TML Pascal v2.0 introduces a new function which is 
intended to mimic the Toolbox function BitAnd (and 
unfortunately uses the same name), in a more efficient 
manner. This function does not work properly with a longint 
type of variable. In the following expression 


var a,b : longint; 
a :-BitAnd(b, $FFFFFFO0), 


the upper half of a will always be zeroed, independent of the 
value of b. A simple way around this is to use the Toolbox 
function BitAnd. However, note that the InLine expression 
for this function (as well as BitOr, BitXor, and BitNot) is 
not in the MacIntf.pas source file. They must be added to 
this file (or your own file). Their associated trap addresses are 
$A858, $A85B, $A859, and $A85A, respectively. I renamed 
them BitAndO, BitOr0, BitXor0, and BitNot0 in order 
to distinguish them from the Pascal versions. I have not 
tested the functions BitOr, BitXor or BitNot. 


4) The compiler directive '(U«' is intended to allow 
libraries to be linked to a new segment, rather than the same 
segment, as with the '(U' directive. The compiler does not 
seem to distinguish between the two directives, however, 
interpreting '(U«' the same as '(U', and therefore it does not 
add the 'new segment symbols to the link control file. A 
simple workaround for this is to replace each line of the form 

(U« libraryname) 


with the two lines 
{U<} 
{U libraryname} 


This will add the appropriate symbols to the link control file. 

I don't pretend to have done a thorough review of the 
version 2.0 update, but these modifications got my program 
humming along again. I've spoken with Darryl Lovato at 
TML about these problems and sent him a copy of this letter. 

is one compiles ok: 
unit unitA; 
INTERFACE 

procedure routineA1; 
IMPLEMENTATION 

procedure routineA1; 

begin 

end; 
end. 
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This one compiles ok too: 
unit unitB; 
INTERFACE 
uses unitA; 
procedure routineB1; 
procedure routineB2; 
IMPLEMENTATION 


procedure routineB2; 
begin 
routineB1; 
routineA1; 
end; 
end. 


This one generates a compiler error: 


unit unitC; 
INTERFACE 
uses unitA; 
procedure routineB1; 
procedure routineB2; 
IMPLEMENTATION 


begin 


procedure routineB2; 
begin 
routineA1; 
routineB1; 
end; 
end. 


This is the error: 
unit C.pas 
28 end. 
^1 
(1) Forward declared subprogram "routineA 1" not completed in 
previous block. 


Stolen Update Events Returned 
Peter J. McInerney 
Auckland, New Zealand 

This is just a short note to clear up a fundamental 
misconception about the handling of updates that appears in 
Scott Boyd's "Pop-Up Window Scroller" (Vol 2 No 9). He 
says that he wants to prevent OverViewSelect being called if 
there are any pending Update events for the front window. He 
says this is accomplished "By doing a BeginUpdate and an 
EndUpdate for FrontWindow", and sure enough that is what 
appears in the program, commented as stealing the update 
events. It does nothing of the sort (in fact it does nothing at 
all, practically speaking). According to Inside Macintosh 
“BeginUpdate replaces the visRgn of the window's grafPort 
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with the intersection of the visRgn and the update region and 
then sets the window's normal VisRgn". Disassembly of 
these routines in ROM reveals that this is exactly and only 
what these routines do. They do nothing to the event queue 
and do not even require that an update event has been 
previously posted. You could for example call your Update 
routine at any time to redraw your window, without passing 
throught the event loop, provided the update region had been 
altered to reflect the region required to be redrawn (there is no 
particular reason to do this, by the way). A further 
consequence is that if the window to be updated is genuinely 
the front window, then omitting the BeginUpdate and 
EndUpdate should have no visible effect when the window is 
redrawn (again this is not a suggestion). 


Since Scott's program works, either his argument about 
updates for the frontwindow is wrong or he has been lucky so 
far. Assuming he has been lucky, how could he steal the 
update events as required? There are at least two methods that 
would work. One way is to call FlushEvents with a mask set 
just for Update events. In the circumstances of this program I 
dont think any problems should arise, but the possibility 
exists (because of their low priority) that update events for 
other windows might be erroneously discarded. Another 
method, which avoids this problem, is to InvalRect the 
portRect of the window and let the events take their course. In 
fact, it is almost certain that neither of these actions is 
necessary. Update events are primarily a mechanism for the 
window manager to handle overlapping windows, and unless 
you are moving windows around, you have to work hard (with 
InvalRect and InvalRgn) to generate them. I don't think there 
are any Quickdraw routines that by themselves generate 
updates or change the update region of a window (if anyone 
knows differently I would like to know). ScrollRect seems at 
first glance to be an exception, since one of its parameters is 
given as a region called updateRgn. But this is not the update 
region of a window (unless you say it is) and is merely the 
region you may wish to update (using InvalRgn) if you want. 
This last point seems to have confused more than one person. 
I recall seeing an example program (I think from Apple) in 
which the updateRgn which didn't need to be redrawn after a 
ScrollRect was operated on by a ValidRgn to "increase 
performance". 

I hope the above clears up the mystery somewhat. 


Mouse Droppings Editor 

Phil Russell 

Waldport, OR 
Since I live in a small coastal town, I am the resident 
computer resource person - by default, I assure you. I often 
get calls from people with questions about computers. This 
morning a woman called saying she had just bought a Tandy, 
and she hated it already. What could I say? Right! "You 

should have bought a Macintosh." 

In another instance, a local IBM true blue believer walked 
into The South Lincoln News after looking at the first edition 
[of Mouse Droppings] containing Macintosh/LaserWriter4- 


585 


text. 

"Thats not done on a computer," he says. "I know 
printing, and that was typeset." I set ALL text for the paper 
on the Mac, and run all text and ads on my LaserWriter+. 
Ain't that a gas? 

It's fun being a Macintosh fanatic. 

Credit Where It's Due 
Andrew Shebanow 
Berkeley, CA 

It would be nice if you could mention sometime that 
IMLib [FinderParams.c, the parameter ram asm routines used 
in Frank Alviani's "Bath Document Spooler" in the September 
issue of MacTutor. ] is now being distributed, in a highly 
improved form, as an integral part of Consulair's Mac C 
product. 

Also please be aware that the information about the 
IMLib library you published in Mousehole Report was 
incorrect: the library was written almost entirely by me, not 
by "a bunch of guys from the BMUG Developers Group." 
Although I am a member of that group, IMLib was not a 
BMUOG Developers Group project. It was just something I did 
on my own which grew out of my own needs, and became a 
complete library out of some strange desire for completeness 
on my part. 

Good luck with your magazine. 

Crash Avoidance 
Jim Matthews 
Honolulu, HI 

I enjoyed meeting the MacTutor crew at the Honolulu 
Computerland show - so nice to see people from the Mac 
Community this far out in the ocean. I wanted to follow up 
on a programming tip I mentioned to Dave: passing the 
address of a resume procedure to the InitDialogs call. In every 
programming example I've ever seen, and in most commercial 
software, the programmer passes NIL to InitDialogs. Thus, 
when the program inevitably crashes, the Resume button in 
the SysAlert is dimmed. This is discouraging to both users 
and developers, since there is no recourse but a time- 
consuming and ramdisk-destroying reset. For developers, 
however, the solution is very simple. Set up a procedure that 
does nothing but call ExitToShell, and pass its address to 
InitDialogs (c example follows): 


void resume() 


ExitToShell(); 


And, instead of 
InitDialogs(OL); 

write 
InitDialogs(resume); 


More often than not, this simple step will let you exit 
from crashes gracefully, restarting the Finder, Switcher, the 
Aztec shell, the LightSpeed system, or whatever shell you are 
working under. It also tells end users that their misfortune 
was not so great as to require a total reboot - they can just 
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start the program again. It's a shame that MacWrite, 
MacPaint, etc., do not take this precaution, but at least future 
programs can take advantage of it. 
User Warning About MacUnderground 
Craig A. Shelley 
Henrietta, NY 

I feel a personal obligation to warn the community of 
Mac users to use extreme caution in dealing with 
MacUnderground, also known as Online Publishing 
Incorporated. I sent them an order for a 20 MB SCSI disk 
drive in May. They spent the money without shipping us a 
drive. They claim they don't even have enough funds to give 
us a full refund. I encourage other Mac users that have had 
such dealings with MacUnderground to call their local 
Postmaster so that they can receive the form to file a report 
with the criminal investigation section of the U.S. Post Office 
in Chicago. [NOTE: We followed up on this. Mr. Shelley 
did order a Peak 20-meg SCSI hard drive for $827.92 from 
MacUnderground in May of this year. The facts above are 
correct. After numerous calls, a registered letter and initiation 
of court proceedings, MacUnderground has agreed to reimburse 
Shelley $100 a week, including about $25 extra for his calls 
and trouble. He is owed $552.92 as of this writing, and has 
since purchased a drive from Mirror Technologies. We also 
called MacUnderground (Fairfield Iowa) several times but 
received only busy signals.- LGM] 

Wanna Write An Editor? 
James G. Haberly 
Mission Hills, CA 

I think MacTutor is in a position to perform a large 
service for the users, and it is one that no other magazine or 
group is likely to be able to do even if they had the 
inclination. 

All programmers, whether they work on a mainframe or a 
micro, have a favorite editor. They always cast aspersions on 
all other other editors (even while secretly admiring some of 
the features), proclaiming that theirs is the only one that can 
really do the job. 

What I would propose is something along the following 
lines. I can supply a module that supports all of the common 
text editing features: multiple windows, the cut/paste group, 
scrolling, opening and saving files, and then add one more 
thing. A command line. Anything typed on that command 
line would be assumed to be in the form of "command name" 
followed (optionally) by some number of arguments. 

An article some time back talked about something that 
the author called "function resources". That has definite 
advantages. They are easy to make and do not require linking. 

Each "external" command could be given a particular 
signature that would identify it as a command. I have been 
linking .Rel files and producing "code" - lowercase intentional - 

files. The main module would look through the various 
folders to find anything that matched the command name. 
(Thanks to MacTutor's articles, this is now a trivial task). If 
it found something, it could lock it in memory and pass the 
parameters on the command line to it. If not, then an 
"unknown command" alert would be generated. The external 
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command would also be given information about the current 
window state and a TEHandle. 

Why would anybody want to do this? Because they can 
then add their favorite commands to an existing editor! It will 
not matter what (compiled) language they prefer to write in. 
What single person has time to write a full-featured editor and 
then give it away? A group, however, is a different story. 

Where does your magazine come in? Coordination. 
With your circulation, there will be people sending in the 
commands that they find useful. (If necessary, contributions 
can be directed to me for sorting and testing). Have you ever 
met a programmer who didn't think that his method of 
working was the best possible? Most of the ones that I know 
are quite willing to show me how to do things their way, even 
when my interest level is negative. 

Why would your magazine want to do this? The primary 
purpose would be to help the Mac programming community. 
An editor which 6000 people have an opportunity to 
participate in building should have features galore. (Of course 
if you happen to make a little bit of money sending out source 
code disks with the latest and greatest commands, nobody is 
likely to complain). 

In any case, please take a little bit of time and think 
about the idea. Who knows what your readers could come up 
with if they were given a little bit of encouragement and 
leadership? 

Fix For Reminder Program 
John McMullen 
Summer Hill, Australia 

In MacTutor's August '86 Mousehole Report, a reader 
signing themself "The Toolsmith" wrote of problems 
experienced with a reminder program downloaded from a BBS. 
Although the name of the program was not given, it is 
possible that it is an early demo version of one of our products - 

Smart Alarms. 

The problem described is probably due to the way Smart 
Alarms, at least in that early version, searched the HFS 
directory for its Reminder file. The search was made by using 
a _OpenWD call before searching each directory and a 
-CloseWD call when through with that directory. 

Versions of the Finder released shortly after this version 
of Smart Alarms became confused because their working 
directories were being closed behind their backs. Of course 
later versions of Smart Alarms and its Demo do not have this 
problem. 

The only possible solution is to replace the system file. 
Possibly the Installer terminated with an error after partially 
installing. The latest version of the program is 2.1 Enquires 
should be made through the U.S. publisher and distributor: 
Imagine Software, 2000 Centre Street, Ste. 1260, Berkeley 
CA, 415-841-0278. 

Copy of Letter to Apple 
Kim Hunter 
Mission Viejo, CA 

Apple has announced version 2.1 of Macintosh Pascal, as 
a free upgrade to previous owners of the original Macintosh 
Pascal. A call to the most competent Apple dealer in my area 
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indicated they [the dealers] knew nothing of this product 
update. 

This occurred at the same time Think Technologies has 
released Lightspeed Pascal. You are probably not even aware 
that Lightspeed IS Macintosh Pascal, vastly upgraded to a 
highly perfected programming environment. I just received 
my copy and it is an excellent, well-supported product. 

Also at this same time, TML Systems has released 
version 2.0 of the TML MacLanguage Series Pascal 
programming system. The original TML version was the first 
real Pascal programming environment for the Macintosh. I 
have the original version and have ordered TML version 2. 
TML supports their products. 

Also at this time, Borland International has finally 
announced TurboPascal for the Macintosh. I have ordered 
TurboPascal and expect to get the same excellent support I had 
with Apple II Turbo, and PC version. 

Rumor has it that Apple intends to release MPW 
(Macintosh Programmer's Workshop) and beta copies are 
circulating. I have copies of code written for MPW, but do 
not have the compiler, and don't intend to get it. 

I urge Apple to discontinue sales under its own label, and 
to release the products back to the original writers if they wish 
to sell them. Apple doesn't do a good job in supporting 
Software, and Apple does a disservice both to its hardware 
customers by perpetuating products with no technical Support, 
and to third-party software developers who are offering 
competent products. Naive computer buyers are lead astray by 
tending to think that products with "Apple's blessed label" 
may be superior because they are the first available, a noble 
gesture, but they hang around too long. Of course, MPW 
doesn't fall in this category, and therefore seems to have no 
purpose in Apple's strategy. 

A company that wants to climb to the top has to stop 
Shooting itself in the foot. [Funny you should put it that 
way...didn't I see an editorial about that very thing 
somewhere? We agree with this sentiment and are not even 
sure MPW is really necessary... Ed.] 

No-Stick Label Printer 
Charlie Jackson 
San Diego, CA 

I enjoyed your Viewpoint (MacTutor, May 1986) about 
the shortcomings of the Macintosh as a business computer. 
Much of what you said was right on target. But in response 
to your detailed exposé of problems with printing labels, I 
would like to call your attention to our program, Silicon 
Press. It is an extremely flexible label printing utility that 
addresses all the problems you mentioned and much more. 

Silicon Press can print any size label, as many across as 
you want, allows you to mix graphics and text freely, merge- 
prints from a text data file or directly from an OverVUE file 
and prints in color on an ImageWriterll. It never rolls the 
platen backwards, avoiding almost all problems of getting 
labels stuck inside an ImageWriter. It allows you to manually 
set the page size or it sets it automatically to the label size if 
you chose "Continuous" forms. 

More on MacFORTH 
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William Hole 
Washington, DC 

Thank you for your response to my previous letter 
concerning the lack of MacForth coverage in your otherwise 
wonderful magazine. It was a pleasant surprise to find an 
editor willing to take the time to respond to one of his readers 
personally. 

Your letter happened to arrive the same day as the 
September issue of MacTutor. I was very pleased to find 
MacFORTH addressed in Jórg Langowski's column in that 
issue. His description of MacFORTH Plus was especially 
interesting: our company is a beta site for this product, and it 
is a significant step forward. One feature not mentioned in the 
article is the fact that MacFORTH Plus shares a common 
kernel with other CSI 68000 FORTH kernels including Multi- 
FORTH for the Amiga, the Atari ST, and OS-9 68K and Unix 
systems. This provides a level of portability not normally 
found in Forth systems without sacrificing the Mac-specific 
features we've come to depend on. 

In regards to your comparison of MacFORTH and Mach 
1: I am always glad to see quality software, especially 
development systems, become available at reasonable prices. 
We were very excited here to obtain a copy of Mach 1 for that 
reason. We evaluated it carefully and decided to stay with 
MacFORTH. 

I don't want to get into all the reasons we were 
unimpressed with Mach 1, because bad-mouthing contributes 
nothing and I have no reason to try to get anyone to switch 
from an environment they find useful. Mach 1 is a good 
product and is unquestionably a bargain, but we find 
MacFORTH to be a more mature and usable system. When 
youre spending hundreds of man-hours developing software 
products, the difference in price between Mach 1 and 
MacFORTH is insignificant compared to the savings to be 
realized by using a truly professional development package. 

Lightspeed Not .Rel Compatible 
Dave Roberts 
Santa Barbara, CA 

Okay, guys. I just don't understand it. A few months 
ago, everybody and their brother is jumping all over 
Microsoft's back for not having their Fortran be MDS .Rel 
compatible. Then, starting a few months back, everybody had 
begun to tout Lightspeed's stuff. Although it sound great 
(read fast), it isn't .Rel file compatible. There is a convertor, 
but.. Anyway, far be it from me to stand in the way of 
progress, but I think it would be good to start getting a 
consistent, if not united, front. I personally thought it was a 
great idea to have a .Rel standard so you could link different 
languages. Being able to write in MacC and use TML for 
filter procs and so forth would be nice to avoid glue (but with 
MacC 5.0 and its "pascal" function definition, I guess that 
also became irrelevant). 

If the reason that everybody is switching is speed, I can 
somewhat agree, but if it's for the HFS issue, as David Smith 
suggested in the September issue, I think it would be nice to 
standardize on a single system. 

As a solution to the HFS problem, I suggest the idea of 
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being able to specify a path name (as in the MacC path 
manager) or, if no path is given, having the appropriate 
program do a complete downward tree search, starting from the 
folder that the searching program resides in. Though I don't 
have HFS or a hard disk, it seems to me that most people 
would probably have their sources, includes and libraries in 
folders that were subordinate to their programming system 
files folder (the one that contains Edit, C, Link, the Exec, or 
whatever). In fact that is the way Consulair hints at in the 
Path Manager documentation. Just thought I'd throw in my 
two cents. 

[Okay, here is my two cents. The Fortran compatibility 
is needed because of limitations of MS Fortran that make 
creating an ASM source file and assembling it under MDS or 
Consulair C, a highly desirable feature, but it can't be done 
because the run time subroutine is not linkable under MDS 
and MDS routines are not linkable under Fortran. A catch-22 
situation. The LightSpeed Pascal system is complete. It can 
produce any type of code, and so there is no reason to go from 
LS back to MDS. As long as MDS routines can be moved 
into a project, you have everything you need. I've tried to hold 
to the MDS ".Rel" file standard, but Apple has effectively 
killed that with the design of MPW, so now we have no 
standard and that is unfortunate. It's every compiler maker for 
himself now. -Ed] 

Serial Port Help 
Glen Leatherman 

1) The book "Assembly Language Primer for the Mac", 
by Keith Mathews for The Waite Group, although simplistic 
and thorough as stated in your review in the May issue, 
sometimes takes things for granted, as if they were just 
reviewing what should have already been known. Also, the 
lack of appendices and even a glossary make it difficult to find 
out something you are unclear on. A great remedy for this 
lack of reference material is the second volume of Macintosh 
Revealed, by Chernicoff. 

2) I know many programmers struggling with the serial 
ports, trying to get the darn modem working with their 
programs. So, in keeping with the trend to base the monthly 
issues on a particular theme, how about a Special 
Telecommunications Issue? Or is it just too long to fit on the 
cover? 

3) A friend has the new Lightspeed Pascal package and 
Says it is really fantastic. Any plans to base some articles on 
it? [The Intermediate Mac'ing column uses LS Pascal. -Ed] 


For the best in technical programming 
information, get The Best of MacTutor, Vol. 1 
A 512 page giant collection of all the articles 


from the first year of MacTutor. Only $24.95 
at selected B. Dalton Bookstores, or order 
direct from MacTutor. 
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Letters 


A Great Resource 
Anthony Urrico 
North Kingstown, RI 

I am delighted to see that the Best of MacTutor is now 
available. I have been receiving MacTutor for six months 
now and I find it to be an indispensible resource when it 
comes to the Macintosh. Even reading the articles based on 
languages that I am not familiar with provides useful insights 
into the inner workings of the Mac. I especially like the 
articles that demonstrate the use of various Mac programming 
techniques through the development of small applications. 
This type of article is particularly enlightening, for it provides 
both a technical discussion of the relevant concepts as well as 
meaningful program examples that demonstrate the use of 
these concepts. I hope to see more of this type of article as 
well as more articles using Modula-2, since Modula-2 
(MacMeth from the Modula corporation) is my language of 
choice. 

Although I am not an "expert" programmer (yet), in the 
course of my graduate work I have read many computer 
journals, and none provides the reader with more practical 
information about programming than MacTutor. I take my 
hat off to you and your staff. 

ZBasic is Bug Free 
Howard Craft 
Washington, D.C 

As described by some of your other readers, I have lived 
through the frustrations of the series of bug-fixes of ZBasic. 
Last week I received version 3.2. The bugs are gone! As far 
as my programs are concerned (each is about 120K of code), 
there are no more system bombs, no more freezes, and what 
works on the Mac Plus works on the Mac 512K. Hurray, the 
Gariepy's of Zedcor have produced what I consider to be the 
ultimate development package for the Mac! With each new 
beta version, they have added new features until there is no 
longer a need to understand very much about Inside Macintosh. 
I am free to pursue MY ideas, not the inner workings of the 
Macintosh ROM. I have one request to make of Zedcor, 
however. Do the same for the IIGS, the ST and MS-DOS 
running under Windows and I'll be ecstatic. Then I can stop 
worrying about how I'm ever going to convert my thousands 
of lines of code into C so that I can create programs with the 
elegance and sophistication that I can now write for the Mac 
using ZBasic. 

No Business Mags Please! 
Byron G. Zollars 
Belmont MA 

Yours is the best Mac magazine I've ever seen. Keep up 
the good technical articles that have made your magazine stand 
out from the "business-oriented" Mac journals. Please find 
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enclosed an order for all the back issues that I missed by not 
subscribing soon enough. I can't wait to digest them. 
On Mac Languages and Speed 
Robert B. Basham 
Portland, OR 

Mike Morton's October article on timing code segments 
addresses a concern familiar to anyone who works with 
languages other than assembly. Due to my own concerns 
about program speed with Neon, I have made extensive use of 
a timing technique similar to Mike's. After timing almost 
every word in the application I am working on, I have reached 
some tentative conclusions about program speed and 
Macintosh languages: 

1) The Sieve benchmark greatly exaggerates any user- 
apparent speed differences between languages. 

2) Modifications in basic algorithms and language- 
specific techniques can have far more effect on program speed 
than overall language speed. 

3) A user-apparent improvement in speed usually requires 
anywhere from a 4- to 10-fold increase in speed. In other 
words, a screen redraw that seems slow to most users will still 
seem slow if its speed is only doubled (much less improved by 
only 3096 or so). But an exception to this is when you are 
tying to dodge the vertical retrace while drawing on the 
screen. In this instance very small differences in speed can 
determine whether or not the image will be flicker-free. 

4) In screen-oriented programs, almost all of the 
program's time is spent in toolbox calls, which are, of course, 
independent of the program language. 

5) Efficiency bottlenecks other than toolbox calls are 
often confined to very small code segments. By effectively 
identifying such bottlenecks and coding them in assembly, 
supposedly slow languages can rival the fastest compiled 
language in terms of speed. 

(Note: Source code for my Neon timing word is available 
on GEnie as file #171 in the MacPro RoundTable). 

More on Mac Languages and Speed 
Richard Ward 
Des Plaines, IL 

Reading Mike Morton's Advanced Mac'ing article made 
me curious to try to time out a few ROM routines of my 
Own. I tested SetPt, SetRect, AddPt, and EqualRect in both 
LightSpeed Pascal and TML Pascal v2.0. Results are as 


follows: 
SetRect 


Trap SetPt 


Own Routine| 38.8 47.8 60.0 68.7 
GetTrapAddr| 28.3 28.7 36.0 36.7 


In-line Time | 7.8 82 15.8 15.0 
Trap AddPt ^ EqualRect 
Compiler LSP TML LSP TML 


Usual Time [95.8 96.3 76.7 78.3 
Own Routine] 49.3 61.2 81.7 91.7 
GetTrapAddr| 63.3 63.7 66.7 66.7 
In-line Time 114.2 14.3 30.0 30.0 
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This set of timings was done with the loop counter set at 
100,000. Base time for the empty FOR loop statement was 
8.3 usec for LSP and 9.5 usec for TML. 

The times for LSP and TML are nearly identical in every 
case except for the "roll your own routine” where the compiler 
is the turnaround time. This is 8 seconds for LightSpeed and 
59 seconds for TML (on a 512E with a Warp Nine 20-meg 
HD). Ireally enjoy reading MacTutor. Keep up the good 
work! 

Some C Thoughts 
Rollo Silver 
San Cristobal, NM 

Here's perhaps the most poignant bug I've been bitten by 

in more than 30 years programming, man & boy: 


#define b *SS 
#define a SS[-1] 


/* top of (my) stack */ 
/* next to top */ 


(several lines of code involving lots of a's and b's) 
return a/b; 


This bug is a black widow, and it took me many days to 
recover from the bite, praying hard for the souls of Kernighan 
& Ritchie. The last line expands to: 

return SS[-1)/*SS; 

The "/b" is turned into the beginning of a comment (!!) 
and the compiler barfs about a missing semicolon, or some 
such red herring. Most UNIX C compilers have a "-P" 
option, or "-E" in Berkeley 4.2 UNIX C: "Run only the macro 
preprocessor on the named C programs, and send the result to 
the standard output", which quickly unmasks this kind of 
horror show, but most Mac C compilers I've used lack it. I 
swore to myself years ago that I'd always put #definientia in 
parens! 

By the way, my candidates for what's most egregiously 
missing in Mac C systems are: 

1) A symbolic debugger, capable of handling names for 
variables allocated on the stack. 

2) A lint (the next version of Lightspeed C is supposed 
to have a construct which will help catch inconsistencies 
between the formal parameter specs in a function definition 
and the actual parameters given in a call). 

3) A preprocessor-only option in C (Consulair C has it) 

4) A full-featured grep 

5) 32-bit ints (Aztec C68K, Lightspeed C have 16-bit 
ints). 
The lack of 32-bit ints creates more problems than one 
might think. I know you can hide long/short/int choices in 
typdefs - but there are still problems: 

8) Switch statements can't handle quantities » 32767. 

b) You can't have static arrays with » 32767 elements. 

c) You need a special, non-portable "mlalloc" or 
"Imalloc" to allocate dynamic arrays with >32767 elements. 

d) I get lots of system bombs due to stack misalignment 
bugs (mea culpa). 

e) I'm constantly (pun intended) forgetting to put the "L" 
after numerical constants that are (in some contexts!) too long, 
e.g., 100000, and having them silently reduced mod 32768. 
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f) Library functions like write are restricted to writing at 
most 32767 chars. 

g) Finally, the worst possible screw (K&R, sec. 7.4, 
page 189): "If two pointers to objects of the same type are 
subtracted, the result is converted to an int representing the 
number of objects separating the pointed-to objects...". I know 
I can do something like 

((long)p - (long)q)>>2 
if p and q are e.g. pointers to ints too far apart, but...shit! 
How do we get from the PDP-11 world, with its 16-bit address 
space, to the 6800x0 world, with its 24/32 bit contiguous 
address space (leaving segmentation to Intel)? Since this is an 
impossible restriction for the Mac, both Aztec and Lightspeed 
depart from the K&R specification to make the following kind 
of thing work: 

int *p,*q 

p = 0; 

q = p+/5000; 

printf("q-p=%ld\n",q-p); 
except that a properly structured program incorporating that 
fragment and compiled by Aztec C68K (version 1.06h) prints 
"620265475", unless the second arg of printf is explicitly 
cast to long: (long)(q-p). 

On the Macintosh Programming Workshop 
Roger Voss 
Huntsville, AL 

Other than perhaps working on Sun Microsystems 
workstations, I know from the range of my experiences with 
software development systems and programming languages 
that I can state quite unequivocally: Apple's Macintosh 
Programmer's Workshop (MPW) environment is the best, bar 
none, software development system that currently exists 
(notice I didn't was say commercially available) on any 
industry-popular microcomputer. 

The MPW Shell embodies the great ease, simplicity, and 
beauty of Macintosh text processing combined with the power 
of a Unix-like shell. I have seen or used the great editors and 
command shells touted for MS-DOS and a lot of Unix 
systems, but none so far have approached being as impressive 
and highly productive as the MPW Shell/Editor. 

Then there is the flagship language of this environment, 
MPW Object Pascal (the word object denoting that this is a 
hybrid object programming language with such characteristics 
inherited from Smalltalk). MPW Pascal is highly modular 
and separately compilable, a la Modula-2 and Ada. It also has 
a mixture of C-like abilities added to it. The fact that this 
language is object-oriented makes it currently the most modern 
and of course the best production programming language 
around. I should add, though, that the MPW assembler is a 
mind blower. It, too, can be used to do stand alone object- 
programming. 
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Historical Computing 


A Pioneer looks back 


IN THE BEGINNING... 


[ Dick Heiser started the personal computer revolution 
when he opened the world's first computer store in Santa 
Monica, CA. in 1975. In this column he traces those early 
days that laid the foundation for the Apple, Macintosh and all 
the other electronic wonders we enjoy today. A participant of 
the Great Peace March of 1985, Dick is filing his reports "on 
the walk" so to speak and is currently somewhere between 
Barstow and Las Vegas, walking to Washington D.C. for 
peace. We wish him well as he admirably represents the 
personal computing fraternity. -Ed.] 


My first personal computer 


Back in the bad old days, Herbert Grosch announced his 
Law: big computers are more cost-efficient than little ones. 
That was bad news for users; big computers mean arranging 
for authorized account numbers, waiting until unlikely hours 
of the night, and the annoyances of bureaucracies and rules. 
The best way to become a radical is to start by defending the 
establishment: I made elaborate arguments in favor of Grosch's 
Law at Pertec. In 1973, I flipped over, when I saw the 
microprocessors from Intel, and started dreaming of personal 
computers. 

Computer Automation introduced the "Naked Mini", 
claiming that "what this country needs is a good $995 
computer." By the time I had mine outfitted with a Teletype, 
CRT, two floppy disks, and 8K words of core memory, the 
"extras" had increased the cost to $14,000. Another time, I'll 
tell you more about do-it-yourself systems integration. For 
now, just say it was an exciting 18 months, filled with 
surprises and learning. 


The MITS Altair 


So, I was astonished to see the MITS Altair computer on 
the cover of the January '75 Popular Electronics magazine. 
According to the Altair system catalog, you could build an 
Altair system similar to my $14,000 computer, for only 
$4,000. I felt the same, years later, when my $995 Mac 
upgrade depreciated so fast. You'll notice, "once a plunger, 
always a plunger." 

The grand plans for the "Altair business system" were 
premature, however. The catalog specified Pertex (sic) disk 
drives. If they can't spell the name right, they haven't done 
the work yet! It was a long time before that whole system 
came together. 
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The Altair was a blockbuster for both price and 
technology. For $439 you got a kit for the CPU and chassis. 
That was the right price: at that time, its Intel 8080 chip alone 
was selling for over $300! Then, for an extra few hundred 
bucks each, you could build 4K memory boards, serial 
interface cards, even an audio cassette recorder interface. The 
Altair looked just like a minicomputer: rows of switches and 
lights on the front panel. It worked like one, too: it used a 
100-pin open bus design that became known as "S-100". 


In the Wake of the MitsMobile... 


The first time I saw the MitsMobile, it was parked on the 
concrete at the Anaheim Convention Center. The event was 
the National Computer Conference, and the folks at MITS 
were too late to get a real booth. No booth number, no 
Carpet, but they had a spellbinding act anyway: a cheap 
computer running BASIC. Every few minutes, somebody 
touched the power switch and crashed the system; then the 
technical support people had to toggle-in the bootstrap 
program, dash inside the RV to the teletype, and re-load the 
paper tape. 

A few days after the NCC, my wife Lois and I went to 
see the MitsMobile again at a motel in the San Fernando 
valley. We arrived early, just before the last seats were taken. 
Then the aisles were taken, then the hallway out the door. 
The pitch-man began to explain the history of MITS (Micro 
Instrumentation and Telemetry Systems was a model rocket 
telemetry company that almost went broke selling calculator 
kits). Before he could finish his first sentence, someone 
interrupted to ask when the "free binary listing" would be 
available. A steady stream of technical questions followed. 
Lois was impressed — these people were planning to toggle- 
in 2,000-byte programs with the binary switches on the front 
panel! We knew we were among some serious hackers. 
Finally, after a few hours of technical questions, the evening 
adjourned, without ever finishing the history of MITS or 
anything else from the planned presentation. 


...Came the SCCS 


At the MitsMobile meeting, Don Tarbell circulated a 
note tablet. We inscribed our addresses, and were invited to 
his house on Fathers Day for the first meeting of the 
Southern California Computer Society. 125 people showed- 
up for that first meeting; for awhile, the SCCS became the 
fastest-growing organization ever; by extrapolation, in 1980 
the entire population of the earth would join-up. More than 
half of the SCCS'ers at that first meeting had ordered Altairs 
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by prepaid mail order; few had received them yet. 


...and my computer store 


I started my store in July. People would prefer to deal 
with me face-to-face, than to do business by mail. Waiting on 
long-distance for technical help was as frustrating then as now. 
With a simple flyer, a two-line classified ad, and a small 
storefront on Pico Boulevard in West Los Angeles, I was in 
business faster than I expected. My slogan "The Computer 
Store" soon became the name of my business. 

If you came into my store in July 1975, you'd have to 
call me out from the back room. I'd have been soldering on 
my first Altair. The "computer" in the front room would turn 
out to be just a cabinet — a gutless wonder. By August, I got 
the computer working, with 8K BASIC running on a 
teletypewriter. 

Besides kits, you could buy books of BASIC game 
programs. Dave Ahl wrote 701 BASIC Games while he was 
still at DEC; it was one of their most unusual and best-selling 
books. Another good book was What to Do After You Hit 
Return , a dynamic collection of games from Bob Albrecht. 
Bob is a pioneer in teaching people the "hands-on imperative", 
and I learned an enormous amount from his Peoples Computer 
Company newspaper. 

Byte magazine was also for sale in my store then. Issue 
number one, produced by Carl Helmers and Wayne Green, sold 
astonishingly well. It had an electronics surplus feeling to it. 
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I remember ordering some surplus Sanders $10,000 graphics 
terminals for about $100 each. The broker called back to 
explain that they were being sold as scrap, for parts only. 
Fixing them up into working terminals wouldn't be fair. 
Sanders didn't want to find lots of illegitimate babies out there 
with the Sanders name on them. 


Summary 


Was the Altair the first personal computer? No, the 
Mark-8 pre-dated it. The Altair was lots better because it used 
the superior Intel 8080 chip instead of the Intel 8008, and had 
an expandable bus system with interface options. What made 
the Altair the start of an industry, though, was BASIC. Bill 
Gates and Paul Allen had provided a magic ingredient: 
software. 


Was Herb Grosch right about big computers being more 
efficient than little ones? Nowadays, small computers cost 
less per byte and less per MIPS. More importantly, we've 
learned how to use extravagant amounts of computer power. 
The Mac uses tons of power to deliver its graphic object 
interface. It's definitely worth it. Now that micro chips 
deliver power so cheaply, we can have "effectiveness" instead 
of "efficiency". 
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PROBLEMS WITH SILVER LININGS 


Today, Thursday sixth, is a rest day. I'm sitting on the 
lawn at Glen Helen Park, near Devore, California. This is 
where Steve Wozniak organized the US Festival. It's a 
beautiful, green, bowl-shaped area beside two lakes. When it's 
not a rest day, I'm marching in The Great Peace March from 
Los Angeles to Washington, D.C. This is still our first 
week, and today is our first rest day. Glen Helen Park is just 
as ideal for our camping as it was for the US Festival, maybe 
better. We have a lot of organizing to do yet, so there are lots 
of loose ends. 

The computers, including a Macintosh, share an RV with 
the Pro-Peace radio station, WQO, 1630AM. The Mac 
showed up at the last minute, and has proven invaluable. It's 
being used for daily schedules, bulletins, letters, etc. It has 
also taken over route planning from my IBM PC, which has 
been having keyboard problems. Why did I bring an IBM PC 
if I am such a Mac enthusiast? I'm saving my Mac for after 
the march, and sacrificing my IBM to the rigors of camping 
life. Sure enough, I dropped the IBM's keyboard the very first 
day. I've taken the keyboard apart, popped-off non-functional 
keys and fixed them by blowing hard. I've glued the broken 
foot back on. At Radio Shack, I found out the difference 
between a capacitor and a varistor. They fixed our 
uninterruptible power supply for free. It was a nice example 
of community support for The Great Peace March. On the 
way back to camp, I thought of a neat way to prevent the 
burnout from repeating. Fixing "handyman" problems feels 
good. It reminds me of the early days at my computer store. 

LITTLE PROBLEMS 

Operating a store is just a process of solving lots of little 
problems. Cash flow, for example, is a strange little 
problem. It seems like a big problem when you don't have 
enough cash, but it's also a guiding hand from mother nature 
to keep mistakes small enough to recover from them. With 
enough cash, I could have plunged deeply into the wrong 
projects, and would have gone out of business. The funny 
thing about cash requirements, is that they go up if business 
goes up, and go up if business goes down. When sales 
increase, I re-order big quantities, and need lots of cash for 
C.O.D. shipments. When business slackens, the credit bills 
become due, and fixed expenses eat-up cash as well. My 
advice to entrepreneurs: Get Don Lancaster's book The 
Incredible secret Money Machine and read it carefully. 

Inventory space was another problem. I'm glad I resisted 
the urge to get proper inventory shelves. We piddled along for 
seven years with a few cardboard boxes stacked on edge. Not 
having enough space for inventory kept us lean. That's very 
important in the computer business where inventory can cost a 
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thousand dollars per cubic foot! Nowadays stores seem to 
have more resourses. but it was a struggle for us to do 
$80,000 in monthly turnover with $100,000 worth of 
inventory. 

Another little problem was limiting what we carried. We 
sold ultraviolet lamps to erase your EPROMS, anti-static 
carpets to protect your keyboard, cables, connectors, etc. 
Where could we draw the line? Everything is connected. 
Somebody needs every possible item - thats why it exists. 
We refused to sell general electronic parts, and sent prospects 
elsewhere for bookkeeping software, for example. Some 
items that customers needed badly, we found hard to sell: 
Metal cases for keyboards were a huge hassle. A local fellow 
tried to make them, but couldn't control schedules or quality. 
Used Teletypes (the Volkswagens of the computer industry) 
were hard to find, and Teletype dealers were a surly lot. In the 
beginning, nobody knew what a computer store should sell, so 
every store decided for itself. 

BIG PROBLEM: PROFIT MARGINS 

The personal computer industry has always had trouble 
with profit margins. Because we started with mail order 
products, the discounts available to dealers started out very 
low. 

My first negotiations with MITS were based on a set of 
simple pencil-and-paper spreadsheets. I prepared three plans: 
Optimistic, Pessimistic, and Best-Guess. Since this was a 
completely new kind of business, it's not surprising that all 
the estimates were wildly off. I had calculated sales at 
$450.00 per computer instead of the $2000.00 per computer 
that would have been a better guess. On the basis of my plan, 
MITS offered to supply kits on an OEM discount schedule. 
Original Equipment Manufactures sell products to a reseller 
(now called a Value Added Reseller or VAR), at a discount that 
depends on quantity. To avoid being fooled by big promises 
of future quantities, these deals usually begin with very 
modest discounts that only get good when the significant 
volume is actually achieved.This would have made it hard to 
start a business with limited capital, because profits would be 
postponed along with the discounts. My first order to MITS 
was at only a 15% discount from list prices; not enough. 

MITS increased the discount, and created a dealer plan 
when they realized stores like mine would be good for them. 
They wanted me to succeed. So I placed another order, at 25% 
off, and we went on to do a lot of business together. 
Discounts remained at 20% to 25% off list until Apple came 
along. All dealers complained about these unrealistically low 
profit margins. 

When Apple offered 35% discounts to dealers, I 
shuddered. It was too good to be true. Sure enough, price 
wars between Apple Dealers shaved the gross profit margin to 
10% - 15%, and I found it harder to make money in the later 
big business years than in the early years when all the dealers 
were griping about short margins. Nowadays, dealers are 
going down the tubes (or, as the Germans have it, 
"Rorchenhin Unterdurchgang"), trying to do business at 596 - 

10% margins, even without paying hackers to provide 
answers and training. I call this a "Big Proglem" because I 
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don't have an answer yet. The Law of Survival is a good way 
to separate the weak from the strong, but I've seen too many 
tough-guy discounters in my neighborhood, Olympic Sales 
and Computique, have reorganized under Chapter XI. Survival 
of the fittest, yes, but there should be more to fitness than just 
price. 

BIG PROBLEM: EXCLUSIVE DEALERSHIPS 

This almost ruined me. MITS refused to allow dealers to 
carry competing products. They believed it was an illegal 
demand, but they made it, verbally, anyway. I started as an 
ALTAIR dealer, but new products from IMSAI and Processor 
Technology looked interesting. MITS threatened to cancel the 
dealership of anyone who carried other brands. The MITS 
people tried to protect their leadership position the wrong way. 

Brand-name competition in iron wasted enormous 
amounts of time. People would come to The Computer Store 
to ask, "Why is an ALTAIR better than an IMSAI?" We 
responded, "Choose a computer that can do a function or solve 
a problem, don't just choose some brand of iron." I'm sure 
most people believed we were just defensive about the 
ALTAIR, but we really believed in Solving a problem with 
Software and hardware, rather than selling features of brand- 
name iron. We could honestly recommend the ALTAIR 
computer, and we were especially impressed with ALTAIR 
software, but we grew tired of defending our choice of brands. 

Many dealers left MITS because of their prohibition on 
competitive brands. Finally, we too changed brands and lost 
the MITS ALTAIR line. I delayed for over a year and finally 
acted with fear. I fully expected our customers to associate us 
only with MITS, and expected them to stop dealing with us. I 
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imagined it would be like starting business all over again. 
After we changed lines, I was astonished: Not one customer 
left us! Customers understood, after all: Iron is secondary; 
problem-solving is primary. This was a big problem that 
ruined MITS, almost ruined my store, and wasted a lot of 
energy. 
BIG PROBLEM: BUILDING 
RELATIONSHIPS WITH PROSPECTS 

IBM Mainframe installations are locked-in to IBM by a 
huge investment in programs, procedures, training, and 
momentum. At The Computer Store, we put a lot of effort 
into before-the-sale problem analysis and planning with the 
prospect. When we completed this planning process, we 
developed a list of recommended hardware and software with 
prices. For our prospect, this became his shopping list! Our 
effort was always appreciated, but everyone's a price-shopper, 
too. We tried to think of ways to get "account control", or to 
sell our consulting services, but we never solved this problem. 
Neither has anybody else, to my knowledge. 

COMPARING TWO ENVIRONMENTS 

Working at The Computer Store was an exciting job. 
We responded to an enormous variety of requests. We 
designed, recommended, specified, configured, installed, 
trained, debugged, and fixed computer systems for every 
conceivable application. Perhaps that is the answer after all; 
helping people help themselves! 
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Confessions of a Computer Store Junkie 


The Right Stuff 

According to Tom Wolfe, the Mercury astronauts showed 
the Right Stuff by staying calm in a crisis and by acting 
correctly, immediately, effeortlessly. Unconventional business 
practices that succeed carry a similar feeling of style, of the 
Right Stuff. 

Michael Phillip's book Honest Business shows small 
businesses how to have the Right Stuff. He recommends 
investing money slowly, paying bills immediately, telling the 
truth, not having secrets, and keeping the focus on people 
rather than on goods or money. 

Carbon Copies 

Many business practices become "de facto standards" 
because everybody copies what the first guy did. Sometimes 
that's smart: Kaypro copied Osborne's portability and price 
because Osborne had proven his new ideas. In my store, I 
copied the IBM "solution sell" because it's the proper way to 
treat a customer. 

The "solution sell" is more like counseling than like 
persuading, and it requires enough time to identify the problem 
or requirements, develop a solution, and explain it. The 
"solution sell" is harder to copy than other practices— which 
makes it a good competitive strategy. 

Sometimes copying can get ridiculous. At first, my store 
was open very late. I liked to jog at noon, and wanted to be 
open after work for computer hobbyists. Can you believe it? 
Other stores copied my hours! For years, most computer 
stores were closed on Monday. Why? Because I wanted to be 
open on weekends instead! Other times the Right Stuff is so 
strange that competitors wouldnt touch it with a ten-foot 
pole! 

Hire the Hacker 

Hackers have been the best employees by far at the 
Computer Store. They're easy to find, hard working, 
fantastically well-informed, and fun to work with. 

In the fall of 1975, when I was busy with customers, my 
wife Lois (then a programmer for the RAND Corporation) 
would pitch-in. Often people wouldn't let her help them, under 
the assumption that a woman couldn't master technical 
material. 

At times, customers had to help each other. Mike Eusey 
helped other customers a lot. He built his Altair computer 
from a kit, and learned how it worked. He began hanging out 
at the store more and more. Lois, expasperated at trying to 
help uncooperative males, suggested we hire him. He already 
knew what to do: he'd been doing it for free! Mike and I 
worked together until I left the store in the spring of 1981 
when I sold the store. Mike is not a stereotypical hacker; he's 
quiet, neat, and sleeps at night. He's a real hacker though; he's 
an information collector, precise, and he knows five ways to 
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do anything. Lately, he's been answering customer questions 
about Telo's Filevision. 

Steve Zook was another famous fixture in the early days 
of the world's first Computer Store. Steve was a freshman at 
UCLA when he built his Altair. He loved to show off his 
knowledge at my store, and was hired soon after Mike. I can't 
remember Steve's electronics credentials, but he was appointed 
repair technician immediately. I was useless with electronics 
and needed his help desperately. Steve fixed a lot of broken and 
mis-assembled kit computers [including mine! -Ed.], but upset 
some customers by casually referring to them as "turkeys". He 
could operate the bit switches on an Altair so fast you couldn't 
see his hands move, and he was hardly ever stumped. In his 
spare time, he rewrote the Processor Technology 
monitor/editor, and it gradually evolved into the Microopolis 
Disk Operating System. Micropolis then hired him so they 
wouln't have to shell out so much for their next operating 
system. What a talent! What took me fifteen years to learn, 
was "obvious" to him. 

The wonderful hackers who have worked at The 
Computer Store have so much Right Stuff, that I'll just have 
to keep some more stories for later. 

Own What You Sell 

The few times I hired a non-computer-owner to work in 
my store, I regretted it. Computer owners are the right kind of 
prospective employees because they have already shown 
sincere interest in the computer, and they already understand 
how it works! 

Owning what you sell today is harder than in the days of 
the Apple II. How many salespeople would want to buy an 
IBM PC-AT, or could afford one? Today's business-oriented 
computer sellers probably don't own any computer, much less 
the one they recommend. 

I enouraged employees to expand their computers by 
selling them equipment at cost. I was a bad sport about 
upgrades, though. I thought frequent equipment turnover 
would be a problem. Now I see that the best employees are 
only happy if they have the latest model, and I should have let 
them upgrade frequently. 

Apple Computer has a great employee ownership plan 
too. Their best idea is the Own-A-Mac program. This plan 
took the initiative to provide discounts for store empoyees 
everywhere. This is absolutely the Right Stuff. It's generous, 
makes people happy, and promotes Apple products. Perfect! 

Open Door Policy 

When I owned the Computer Store, every employee had a 
key to the door and to the burglar alarm. To me, the store is a 
big toy factory, and I want everyone to be able to play with 
the toys as often as possible. Giving out so many keys 
increased the chance of something being taken, but I don't 
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believe anything ever was. Instead, everyone responded with a 
sense of responsibility and pride, and they mostly cleaned-up 
late night messes. Some of the late night sessions led to 
interesting software such as PDS-1, ModMon and VTL-2; 
other sessions were just for fun or for exploring. I'm glad 
insurance companies didn't think to ask "How many keys are 
in use?" back then. They'd never have understood how much 
fun it is to have your own key to the door! 
Kids Welcome 

Some kids were timid about approaching the computers 
in the store. Most weren't. Kids exemplify the hacker ethic: 
they're hands-on-oriented, patient, and insatiably curious. 

Many adults are encouraged by seeing kids use 
computers. We tend to overlook the fears and inhibitions other 
people have about computers. One adult explained "We've 
been told too many times not to break things, so we're afraid 
to play with them". Another adult suggested that we're afraid 
of getting beeped-at for a silly mistake. "Getting his hand 
slapped" for doing something invalid really makes him irate. 
Non-hacker adults have no idea how much you can learn by 
experimenting. 

When I teach adults to use computers, I tell them that 
teenagers make the best computerists. I encourage adult 
students to imitate teenager's curiousity, tenacity, and 
aggressiveness. Some of our customers were put-off by the 
"unbusinesslike" informality of kids using computers in the 
Store. Other propects got the intended message: computers are 
interesting and fun to use. 

Great Books 

Selling books served many purposes for us. First of all, 
the books contain essential information. We sold how-to 
books, reference books, and software manuals. This saved a lot 
of time with propects who ask, "What's this all about?" 

Second, we sold textbooks and monographs. We were one 
of the better local sources for computer science titles, and we 
Stocked some exotic stuff as well. Often there was a "free 
University" atmosphere in the store, when a local expert 
would sound-off. 

Third, we recommended books that promote a special 
viewpoint. Computer Lib by Ted Nelson is my favorite, and a 
new edition may appear later this year. The Psychology of 
Computer Programming by Gerald Weinberg is the proper 
orientation for a new professional programmer. Travels in 
Computerland by Ben Schneiderman is a unique and funny 
description of what can happen when you decide to 
computerize. 

Lois Brand of Peoples Computer Company told me about 
the American Booksellers Association. The ABA's big red bok 
is essentail for dealing with book publishers. Selling books is 
hard work, and discounters are wiping-out some interesting 
book dealers. 

Sometimes the Wrong Stuff hurts you just as much as 
the Right Stuff helps. When I bought some remainder books 
cheap from the Library of Science, I priced them too high. 
Instead of bargains for customers, we had books to count and 
to dust for years and years. The Wrong Stuff Clings; it takes 
prompt and decisive action to drive it away! 


© The Complete MacTutor, Vol. 2 


Parity 

Before winding up this list of proper ideas, I'd like to 
mention some Right Stuff for computer hardware and 
software. Once in a speech, I claimed that IBM will spare no 
expense to put reliability and error checking into your 
computer. I got a laugh, but I was perfectly serious! For 
example, all IBM computers have memory parity checking. 
Sure enough, a few years later, IBM's personal computer 
became the only personal computer with parity memory. 
Surely I told myself, parity will now become a universal 
feature. Unfortunately, it hasn't. 

Some people even object to parity, mistakenly thinking 
it's making them wait for the power-up memory test. That 
memory test itself is annoying and can't be turned-off so it's 
very Wrong Stuff indeed. Some day memory parity checking 
will catch on. Maybe by then we'll have memory error 
correction as well as detection. In the meantime, it's an 
interesting exception to the rule, when IBM Struggles without 
success to give us the Right Stuff. 

Think too about open hardware and software architecture; 
how do you know it's the Right Stuff? 

Shareware 

When I write some software, I want to sell it as 
Shareware, like Bob Wallace does. Shareware, user-supported 
software, and Freeware don't need intimidating license 
"agreements" or copy protection schemes. The Customers, 
instead of being the "enemy", are the primary marketing force. 
Conventional publishing and distribution absorbs 93% of the 
selling price, so the poor conventional software author can't 
even afford to ofter a refund to the customer! 

Software distributed via Compuserve and through user 
groups can be updated smoothly and often. Switcher and Red 
Ryder have both been much more dynamic and more 
responsive to user feedback than more expensive store bought 
software. If Smartcom were user-supported, like Red Ryder, 
would they ignore it's incompatibility with the Tecmar Hard 
Disk? Big software companies generate so much momentum 
and inertia, spending that 93% of the revenue, that it's no 
wonder they're unresponsive. Some "marketing expert" who 
doesn't understand the problem and who probably can't even 
use thé program decides what's important. [So that's why 
Microsoft is having such a hard time figuring out how to 
make Fortran work on a Mac Plus! -Ed.] 

Bob Wallace, on the other hand, is fully in charge of his 
Software as well as his company. He updates his product often, 
and can afford to hire a few talented people to help him. He's 
close to his customers, so he knows what's really important to 
them, and he had the pleasure of knowing that all the revenue 
comes from already satisfied customers. By designing his own 
business arrangements, Bob is way ahead of authors who turn 
their programs over to conventional publishers. 

Do it Yourself 

Many of these ideas are good not only because they work, 
but also because they deserve to work. Computerists, like 
other technologists, face choices between good and bad. Plastic 
guns for airplane hijackers, and teflon bullets are technical 
innovations that can be imagined but should not be developed. 
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Choosing between good and bad isn't hard. It just requires the 
confidence to follow your own judgement. The Rotary 
International "four way test" is a good starting point when 
you're thinking about your own Right Stuff: 

1. Is it the truth? 

2. Is It fair to all concerned? 

3. Will it build goodwill and better friendships? 

4. Will it be beneficial to all concerned? 

Not only is this a good creed for the personal computing 
industry but individuals and nations as well. And now for me, 
it's back to the Great Peace March to emphasize my belief that 
peace is definitely the Right Stuff! — 

P 


tS 


598 


© The Complete MacTutor, Vol. 2 


A Cooperative Venture 

Sometimes the teamwork that makes a successful product 
is hidden, sometimes it's visible. In the case of the Macintosh, 
it's both hidden and visible- the names are molded into the 
inside of the case! The tv typewriter (TVT) was the work of 
four independent people. Don Lancaster, Dan Myers, Josef 
Rosenthal and I worked in succession to design it, to produce 
it as a kit, to modify it into a proper computer terminal, and 
to document the information. Each of us brought the product 
closer to the customer by making it easier to build and more 
useful. 

Mother of Invention 

The Altair personal computer didn't include a built-in 
video terminal. Video terminals sold for $1500 or more, until 
Lear Siegler introduced their $995 "dumb" terminal. But even 
that Lear Siegler terminal was an expensive accessory for a 
personal computer. Used Teletype model 33 teletypewriters 
were expensive too; good ones sold for $800 or more. 
Teletypes are like Volkswagens- they're slow and noisy, but 
they hardly depreciate, and they last forever. 

Everybody who built an Altair needed a low-cost terminal 
for it. The "TV Typewriter 2" from Southwest Technical 
Products Company emerged as a probable best buy. [I had one. 
It was great! -Ed.] The TVT-2 kit cost about $275 by mail. 
Adding a keyboard, power Supply, and serial interface raised 
the price by another $100. 

Don Lancaster - Designer 

"Don Lancaster writes books". That's how the designer of 
the TVT describes himself. He has written about a dozen 
electronics books. Many are still in print long after lesser 
technical books are gone. He's also a volunteer fireman and 
occasional forest ranger. 

His Incredible Secret Money Machine is a wonderful 
career guidance book. Basically he suggests: 


* Work for yourself. 

*  Dosomething you can throw yourself into 
wholeheartedly. 

e Maximize the value you personally add to your product. 

* Look for leverage and royalties. 

*  Dontinvest lots of money in a new business. 


When I referred to this book at the 1984 Hackers 
Conference, the audiance interrupted to cheer. Lots of top 
hackers know this book! Lancaster illustrates his advice by 
talking about himself. As an example of leverage, he explains 
that when he designs an electronics project, he writes a 
magazine article about it, licenses the kit for a royalty, and 
uses the articles as a book chapter. Don's TTL Cookbook and 


O The Complete MacTutor, Vol. 2 


Dick Heiser 
Industry Pioneer 
On the Great Peace March 


TV Typewriter Cookbook were best-sellers in my store. 

Don Myers warned me "Don doesn't like to chat. In fact, 
he doesn't always answer his phone. He's as likely to sleep 
days and work nights as the other way around." When I called 
Don's unlisted number, he turned out to be quite friendly and 
open. He even told me what he planned next for the TVT's 
number 3, 4 and 5! He planned to lower the cost, and add 
color, to develop a terminal more like an Apple II. I tried to 
talk him into more characters per line and lower-case letters, 
because of my interest in computer text editing. Don was on a 
better track than I was. 

TVT Design 

The TV Typewriter-2 displayed 16 lines of 32 upper-case 
Characters in a 5x7 dot matrix. The main circuit board was 
about 11 inches square, with a daughter board for screen 
memory, and optional boards for serial or parallel interface and 
manual or coded cursor movement control. It had connectors 
for a parallel ASCII keyboard, power supply, and video 
monitor. 

The TV Typewriter-2 was an improved design. Lancaster 
used considerable expertise to generate an accurate, standard 
video signal. He was proud of the rock-steady video. The TVT 
was not really a computer terminal, however. For instance, 
new lines of text overwrote old text, so the ends of longer old 
lines showed alongside the new lines. The TVT was a video 
generator, suited for titling and announcements via closed- 
circuit tv, like the ones in hotels, theater lobbies, and airline 
terminals. 

Dan Myers - Kit Producer 

Dan Myers presided over the Southwest Technical 
Products Company in San Antonio, Texas. His company paid 
a royalty to Don Lancaster for the right to sell TVT circuit 
boards and kits. He advertised in magazines like Popular 
Electronics, because the TVT was an electronics project rather 
than a computer peripheral. 

Dan took the printed circuit layout from Don Lancaster 
and had boards made. He prepared bags of integrated circuits, 
resistors, capacitors, and connectors. He printed a brief manual 
with layout diagram and schematic. He also bought the rights 
to a parallel ASCII keyboard design. 

l've never seen Dan in person, but we've learned a lot 
about each other by talking on the phone and by doing 
business together. Dan is a "no frills" businessman, but he 
won't cut corners that he considers important. He wants to 
hold down costs so he can sell low cost products. Don 
Lancaster warned me to expect very short discounts, maybe ten 
percent or less, from Dan. I felt very lucky to negotiate a 
twenty percent discount, and preferred to do all of my business 
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directly with Dan. Sometimes I wondered if he was a one-man 
show back then. 

Unlike MITS and Heathkit, Dan charged extra to fix your 
machine if it didn't work. Dan and Don were well-matched to 
collaborate: they both wanted to control costs first and add 
features second. 

The following year, Dan bought rights to a Motorola 
6800 based computer design. He evaluated it on the basis of 
memory size, clock speed, instruction set, and price. His 6800 
computer was a fantastic hardware value. He advertised it in 
the major computer and electronics magazines, and signed up 
dealers. It was a brave design. Unlike the MITS and IMSAI 
computers, it had no rows of switches and flashing lights. It 
used a "software front panel" which was the Right Stuff; better 
and cheaper. 

His one big mistake was to apply his "no frills" attitude 
to software. Too bad. As Portia Isaacson once said, "After you 
consider the software available for a particular computer, the 
next most important consideration is the color of the cabinet!" 
Software was a hard lesson for Dan. 

The TVT Kit 

When you opened the five cardboard boxes for your TVT, 
serial interface, keyboard, power supply, and cursor control 
board, your emotions reflected your electronics expertise. The 
printed circuit board was a first-class piece of goods; 
fiberglass, two-sided with plated-through holes. You had to 
identify the parts by the codes printed on them. The only 
decoding information was a layout diagram for chip 
replacement, and a color-code list for resistors. Do you like 
Molex connectors? One early customer put the connectors on 
backwards, but they're cheap and they work. 

The keyboard circuit was plated on only one side, so you 
had to solder on perpendicular "bus bars" to stiffen it and to 
supply the horizontal traces. Too little solder and the bus bars 
came loose. Too much heat and the plastic keyswitches would 
melt. It was definitely a challenge for newcomers! 

The keyboards weren't good enough at first. More 
expensive keyswitches, more special characters, and improved 
circuit board layout helped, but these low cost keyboards were 
susceptible to static electricity burnouts. 

Left as an exercise for the kit builder was the problem of 
boxing this collection of boards, figuring out which polarity 
of the keyboard strobe the TVT expected, and finding a video 
monitor. [Hitachi made a great little 9 inch montor, the 905, 
that was very popular. -Ed.] 

Josef Rosenthal - System Engineer 

Joe worked as a programmer for the System Development 
corporation (SDC) in Santa Monica. He built an Altair and a 
TVT early in the product life cylce. That means I sold him the 
stuff before it worked together properly. 

Smiling Joe looked at the misfits between the computer 
and the TVT as a puzzle. He came by the store often to find 
out the latest developments and to share his discoveries. 

Three problems fascinated him. First, the TVT was slow: 
its serial interface operated at only 10 characters per second. It 
was probably intended to connect TVT's to the teletypewriters 
rather than to computers. Joe wanted the interface to work ten 
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times as fast. 

The second problem has been mentioned above: ends of 
old lines of text remained on the screen beside the new lines. 
Listing a Basic program resulted in a gibberish mixture of 
text. Joe worked on a way to erase each line or screen before 
starting to write on it, or to erase to the end of each line before 
responding to a carriage return character. 

The third problem involved taking advantage of a design 
feature. Don Lancaster provided two screens of video memory, 
and the TVT filled them alternately. We wanted to be able to 
switch screens, to review previous data. 

Joe was the only one of us who worked for free. He was 
an enthusiast excited, happy, full of possibilities, curious, 
experimental. He solved all three problems. 

TVT Modifications 

Speeding up the interface turned out to be easy. Joe 
examined the schematic, discovered a divide-by-nine counter in 
the clock circuit, and jumpered it out. The 110 baud circuit (10 
characters per second) would now operate at 990 baud, an 
unlikely speed. No problem: Joe calculated what combination 
of jumpers would make the counter in the Altair's serial 
interface work at 990 baud, and viola, the nine-times speedup 
worked! 

Another magic jumper solved the jumbled lines problem. 
Joe ran a jumper from the linefeed code to a circuit point 
which caused erase-to-end-of-line. Sure enough, it worked! 
Each time the terminal advanced to a new line, the new line 
was cleared. Now the TVT worked as a proper video terminal. 

Joe further experimented with the screen switch logic. He 
could have added integrated circuit chips to switch from one 
screen to the other and vice versa. Instead, he directly wired a 
keyswitch to a screen selector toggle input. Each time you 
pressed that key, you delivered a random jolt to the selector 
toggle. No debouncing! I thought it would feel frustrating to 
operate a random switch, but it worked fine! If the screen didn't 
switch, I'd hit the button again. No sweat. 

Joe also assigned key codes to make the cursor controls 
work right, and figured out keyboard jumpers to accomplish 
this. A few more jumpers supplied special characters like the 
caret or up-arrow, used in Basic programs. Joe accomplished 
magic: something for nothing. Not adding parts is a 
characteristic of elegance and of good hacking. 

Dick Heiser - System Integrator 

I was the last member of this "gang of four." As the 
person responsible to the customer for a successful project, I 
wanted to tie together what Don, Dan, Joe and others had 
discovered. At IBM, I'd learned that, "you're not through until 
the paperwork is done." 

Earlier, I'd written a useful booklet of tips for building 
the Altair computer kit. The TVT booklet suggested which 
kits to obtain, how to orient connectors, gave advice on 
making the keyboard strong and reliable, and illustrated cuts 
and jumpers for strobe polarity, clear newline, screen select, 
special characters, cursor control and serial speed-up. It showed 
how to jumper the MITS serial board for 990 baud. 

I had to revise this booklet as we learned more, and when 
improved keyboards became available. 
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In addition to the booklet, we sold a kit of extra parts, 
including chip sockets, keyboard cable, fuse, switch, screws 
and grommets. We also tried to sell cases for the TVT. 
Unhappily, metal-bending is a low-tech art, and we could not 
find a supplier able to consistently deliver quality. We helped 
people obtain a video monitor, too. We reprinted an article on 
converting tv's and we sold converted tv's and closed-circuit 
monitors. 

TVT Complete 

The manual overcame stumbling-blocks associated with 
the kit, and showed how to make a good $400 video terminal. 
The design and the chips were good enough that, armed with 
the advice in our notes, most customers were successful in 
building a TVT that worked right. Customers found the 
improved TVT easy to build. Our confidence at the store 
increased because our recommendations worked so well. 

Using the TVT 

For several months before we bought a cash register, I 
balanced the receipts with the comptuer. I used the TVT to 
operate the Altair, with a simple Basic program. 

The video terminal gives a computer its "feel". It's 
"where the rubber meets the road." The TVT had a good feel. 
It's big letters (32 characters per line) were highly visible. 
Sometimes I like lots of little characters on the screen for 
context, but usually big characters are visually more relaxing. 
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Naturally, the Macintosh is superior here, allowing either size. 
See if you like writing your draft copies with a larger than 
normal font next time. 

The TVT's full-stroke keyboard allowed confident typing. 
Computer wizard Rick Shiffman would bang the keys so hard 
that weak keyboards would simply break. Thus Heiser's Fifth 
Law: keyboard bashing reflects user confidence- Or poor 
software design! 

TVT's Fate 

Our modified TVT was the "state of the art" for only a 
year. Then, memory-mapped video boards for the Altair came 
along. These character-oriented displays worked like the Apple 
II. A dedicated area of computer memory held ascii codes to 
drive a character generator. 

Polymorphic Systems and Processor Technology 
produced good memory-mapped video boards. This was before 
the era of the CP/M operating System, so softwre device 
drivers were not used. Each program had to be individually 
modified for memory-mapped video. Soon, memory-maped 
video took over, offering Speed, compactness and economy, 
better suited to the powers of personal computers. 

In it's day, the TVT was a key to making the Altair work 
right. I'm proud of the result, happy that our collaboration 
worked out so well. Besides which, it was fun! as 
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Mac Meets Ma Bell 


Protocol Standards 


Mac Binary Standard 

A file transfer protocol specific to the Macintosh that 
originated within the MAUG (Micronet Apple Users Group) 
on Compuserve has gained widespread acceptance and is 
becoming a defacto standard, and is a primary feature of the 
new MacTerminal 2.0 being distributed this month. 

The "MacBinary" protocol (everything earns a label 
nowadays!) allows transmittal of the Data and Resource Forks 
within a Macintosh application and it also transfers the Finder 
information on that particular file ( icons, creation date, size, 
" About" info, etc...). This standard is now being utilized by 
virtually every Macintosh communications software developer 
that I have contacted. Look forward to new versions of 
MacLine, inTouch and Smartcom that will support the 
"MacBinary" XModem standard by the time this article is in 
print. 

Here is a reprint of the technical aspects of the MacBinary 
protocol, courtesy of Dennis Brothers ("MacTep" fame) : 

The binary format described is independent of the 
communication protocol used to accomplish the transfer, and 
assumes only that an 8-bit transparent transfer can be 
accomplished. Such protocols as Christensen (usually referred 
to as XMODEM or MODEM )), Kermit, and CompuServe A 
or B meet this requirement. Because of the proposed standard's 
MacTerminal/KMODEM heritage, there is a requirement that 
the transmitted data be padded (with nulls) to a 128-byte 
boundary at certain points, but this in no way implies that a 
block-oriented protocol must be used. The basic format 
proposed is identical to that used by MacTerminal, by Mike 
Boich and Martin Haeberli, and can be used with a version of 
MacTerminal that has had a patch applied to "normalize" its 
implementation of the XMODEM protocol. 

In brief, the binary format consists of a 128-byte header 
containing all the information necessary to reproduce the 
document's directory entry on the receiving Macintosh; 
followed by the document's Data Fork (if it has one), padded 
with nulls to a multiple of 128 bytes (if necessary); followed 
by the document's Resource Fork (again, padded if necessary). 
The lengths of these forks (either or both of which may be 
Zero) are contained in the header. 

The format of the 128-byte header is as follows (offsets 
and lengths are given in decimal): 

Offset Length Contents 


000 1 Zero. This is a "version" byte. 
001 1 Length of filename. 
002 63 Filename (only "length" bytes are 


significant). 
(the following 16 bytes are a standard Finder Info record) 


065 4 File type. 
069 4 File creator. 
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073 1 Finder flags: 
Bit 7 - Locked. 
Bit 6 - Invisible. 
Bit 5 - Bundle. 
Bit 4 - System. 
Bit 3 - Bozo. 
Bit 2 - Busy. 
Bit 1 - Changed. 
Bit 0 - Inited. 
074 1 Zero. 
075 2 File's vertical position within its window. 
077 2 File's horizontal position within its 
window. 
079 2 File's window or folder ID. 
(End of Finder Info) 
081 1 "Protected" flag (in low order bit). 
082 1 Zero. 
083 4 Data Fork length (bytes, zero if no Data 
Fork). 
087 4 Resource Fork lenth (bytes, zero if no 
R.F.). 
091 4 File's creation date. 
095 4 File's "last modified" date. 
099 27 Zero fill (reserved for expansion of 
standard). 
126 2 Reserved for computer type and OS ID 


(this field will be zero for the current Macintosh). 

Note that it is the responsibility of the receiving terminal 
program to resolve file name conflicts, generally by somehow 
modifying the name of received file if there already exists a file 
with the original name on the target volume. 

Note also that, while the original window or folder ID and 
position may be transmitted, the receiving terminal program 
would not normally set these items for the received file, but 
would instead accept the values that the File Manager assigns 
when it creates the new file. 

It is suggested that Macintosh terminal programs 
implement two modes of protocol transfer: text and document. 
Text mode is used for unformatted files of type TEXT (with 
only a data fork), and document mode (using the binary format 
proposed here) is used for all other files. Document mode may 
also be used on text files, of course, if it is desired to preserve 
such things as the file's creator ID or creation date. 

The intent of text mode is to provide compatibility with 
text files on other systems. Toward that end, it is 
recommended that a linefeed be inserted after each return 
character as the text file is transmitted, and that, in the case of 
block-oriented protocols, the last block be explicitely padded 
with nulls if the text does not end on a block boundary. When 
receiving in text mode, linefeeds and trailing nulls should be 
stripped. If a CTRL-Z (Hex 1A) character is received following 
all other text (and before any null padding), it should also be 
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Stripped (Ctrl-Z is a common text terminator on CP/M and 
some other systems). Note that the above discussion applies 
only to text files transferred under some protocol, where an 
exact image of the transmitted data will be stored in a file on 
the remote system. 

When receiving a file via a protocol, a terminal program 
may distinguish between text and document modes by 
examining bytes 0, 74, and 82 of the first 128 bytes received. 
If they are each zero (and at least 128 bytes have been 
received), then it is a safe assumption that a MacBinary- 
formatted document is being received. Terminal programs 
implementing possible future versions of the proposed 
standard would, of course, accept an appropriate set of version 
numbers in byte 0. Note also that compatible extensions of 
Version 0 of the proposed standard are possible (one such is 
Suggested below) that involve transmission of additional 
information following the information described here. For this 
reason, a terminal program should be implemented so as to 
perform the proper receive procedures for all data sent to it, but 
to ignore any data that it does not know what to do with. 

Since a text-mode document does not contain a file name, 
it is suggested that when text-mode is detected, a file be 
opened under a dummy name on the receiving Macintosh, the 
text written to that file, and the file renamed to a name selected 
by the user (via an SFPutFile box) after the reception is 
completed. This will avoid problems caused by indeterminate 
delays for name selection at the beginning of the file transfer. 

It is desirable to allow the user to specify the destination 
volume in advance of the actual start of transfer for either type 
of transfer. Two methods are suggested for this: provide a 
“Select Destination Volume" menu selection, presumably in 
the menu containing the "Receive File" selection; or query the 
user immediately after the "Receive File" menu selection is 
made. Either or both of these methods could be implemented 
in a given terminal program - the independent "Select Receive 
Volume" method is particularly desirable if the ESC-a/ESC-b 
automatic receive facility (see below) is implemented. The 
volume selection procedure should provide the same functions 
as the volume selection portion of the SFGetFile and 
SFPutFile dialog boxes. 

First Proposed Extension 

It is proposed that the binary format described above be 
extended to allow the transmission of descriptive text with a 
Macintosh document (specifically, the descriptive text from 
the Finder's "Get Info" box for the file being transferred). This 
is to be accomplished in a transparent manner by assigning 
bytes 99 and 100 of the header described above to be used to 
hold the length of the descriptive text (or zero, if there is 
none). The descriptive text, if any, will begin on the 128- 
boundary immediately following the Resource Fork, if 
present, else the Data Fork, if present, else immediately 
following the header if neither fork is present. It is hoped that 
methods for reading and setting a file's "Get Info" text will be 
made public at some point. 

Notes on MacTerminal's XMODEM implementation, and 
a proposed extension: Familiarity with the Christensen 
(XMODEM) protocol is assumed in the following discussion. 
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When doing "Mac-to-Mac" transfers, using the binary 
format described above, unmodified MacTerminal does not use 
a true XMODEM protocol, and is therefore incompatible with 
most non-Mac systems. The differences lie in two specifics: 
the transmitting Macintosh initiates the transfer by sending 
the the two characters ESCAPE (hex 1B) and "a" (hex 61); the 
receiving Macintosh is expected to reply with the character 
ACK (hex 06). The transfer then proceeds using normal 
XMODEM procedures, except that each of the header and the 
two forks (if present) is treated as a separate XMODEM 
transfer, with the transmitting Macintosh waiting for a NAK 
(hex 15), then sending the blocks of that phase (beginning 
with a block number of one), then sending EOT (hex 04) and 
waiting for an ACK (hex 06) from the receiving Macintosh. 

It is proposed that a modified procedure be accepted as a 
standard, to be implemented instead of or in addition to the 
above-described MacTerminal "Mac-to-Mac" protocol in 
complying terminal programs. The modified procedure, which 
is compatible with standard XMODEM implementations, 
functions as follows: The transmitting Macintosh sends the 
two characters ESCAPE (hex 1B) and "b" (hex 62). The 
receiving Macintosh may optionally reply with ACK (hex 06) 
(this is allowed so as to have minimum impact on existing 
MacTerminal-compatible implementations). The transmitting 
Macintosh then awaits receipt of a NAK (hex 15) (or 
optionally a "C" (hex 43), if the receiving terminal program 
supports CRC checking), following which a single, normal 
XMODEM transfer occurs. The transfer may be in text mode 
or document mode, will begin with block number one, and 
block numbers will increment uniformly (modulo 256) 
throughout the transfer. 

It is expected that a patch to MacTerminal making it 
compatible with the above proposed procedure will be 
available in the near future. 

Responses to proposals 

Please address comments or questions on the above 

proposals to: 
Dennis F. Brothers 
197 Old Connecticut Path 
Wayland, MA 01778 
617-358-2863 


CompuServe: 70065,172 
Delphi: DBROTHERS 
MCI Mail: DBROTHERS 


New Communications Programs 

Presently there are a number of new programs that 
incorporate MacBinary, including Red Ryder 6.2, FreeTerm 
1.7, Telescape & VersaTerm. The proliferation of new 
Communications software for the Mac is truly amazing ! 
Most of these are very functional and flexible pieces of 
software. Most incorporate command languages for unattended 
functions, multiple terminal emulations, etc. Others have nice 
little features that make you wonder how you ever got along 
without them. Like the "view file" function from within the . 
"inTouch" program that allows you to review a file (ascii or 
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vidtex) before it is sent or after it is captured; or the pull down 
menu in VersaTerm that allows you to store 8 of your most 
often called numbers and just CALL them without going 
through all kinds of hassle to pull up a new file. I guess a 
dream program would synthesize the best features of all of 
these programs, but right now it isn't as hard to accept what is 
available as it was a little earlier in the life of Mac 
communications. 

Our next few areas of discussion deal with some of the 
latest developments in telecommunications : 2400 baud 
modems and some of the new protocols for higher speed data 
transmission. 

"V.22 bis" is the defacto international standard for 2400 
baud full duplex asynchronous data communications. 
Currently modems from Racal Vadic, Hayes, U.S. Robotics, 
Novation, AT&T and Microcom support this standard. It is a 
creation of the CCITT and as has earned the stamp of approval 
from Bell. The CCITT is actually tied into the United Nations 
and it produces recommendations for communications 
standards in the "X" and "V" categories. The "X" series (such 
as the X.25 standard) applies to packet switched networks such 
as Telenet, Tymnet and Uninet. The "V" series applies to 
ordinary switched telephone lines; the 1200 baud standard is 
V.22 and the 2400 baud standard is now V.22 "bis" (which is 
French for secondary, kinda like the European version of 
revisionitis). In the USA there are some slight modifications 
made to V.22bis to accomodate some of our own domestic 
quirks, ie: switching between Bell 212a and V.22bis (rather 
than V.22); and with call-waiting as a widespread feature they 
have changed the loss of carrier disconnect delay from 40-65 
milliseconds to 600 or more milliseconds. 

Telephone circuits normally have a frequency bandwidth 
that is limited to around 300-3000 cycles per second (also 
known as cps, Hertz.). The carrier signal that the modem 
modulates must fit within this bandwidth, to exceed the 
capacity of this frequency "window" we resort to another type 
of modulation, PHASE encoding. Going beyond representing 
1 and 0 with two different frequencies, we now switch between 
multiple states of phase (for 2400 baud there are 16 states of 
phase, the current Bell 212a standard uses 4 states of phase) 
and divide our information within each state. In V.22bis 
things like "Quadbits" (four consecutive bits) come into play. 
The first two bits in a quadbit define the change of quadrant 
(0, 90, 180, 270 degrees of phase) relative to the quadrant 
occupied by the preceding signal element. The last two bits of 
the quadbit define one of 4 signalling elements related to the 
new quadrant. 

Here is a chart of common baud rates and their appropriate 
carrier states : 


Bit Rate (bps) | BaudRate | Carrier States 
300 300 2 

1200 600 4 

2400 600 16 

4800 1200 16 

9600 2400 32 


Notice how none of the baud rates exceeds the frequency 
bandwidth limit. Remember that this is for FULL DUPLEX 
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transmission. There is a "High" and "Low" channel for 
simultaneous transmission and reception. Each channel 
operating at HALF the overall speed of the unit. At baud rates 
above 2400 line equalization is necessary to combat the poor 
quality of phone lines. The next step beyond V.22bis will be 
V.32. 

V.32 will allow full duplex asynchronous transmissions of 
up to 9600 baud. Telebit of Cupertino (where else 7?) is 
entering into an agreement with a number of heavy 
telecommunications companies to market their new 10K-baud 
modem called the "FastLink" (you'll probably see this under 
the "IRMA" label first). While it is not presently V.32 
compatible, they intend to submit what they feel is a superior 
standard to the CCITT and see if they can have their method 
adopted in lieu of the current V.32 (V.32 "bis" maybe 7). 
Concord Data Systems of Waltham, Mass. (among others) 
intends to release a V.32 standard modem by the end of the 
year. Both the CDS and the Telebit technologies fall into the 
$2,000 per modem bracket. For a LOT of corporations, these 
technologies will pay for themsleves VERY quickly (for 
FAX transmissions among many other things). And WE are 
the folks that will inherit this technology as the prices fall. 
Come on now, admit it ..... wouldn't you just LOVE to have 
one ?? 

NOW, onto the protocols that will be necessary to support 
these high speeds ..... the following two Protocols are in 
contention. X.PC and MNP. X.PC is being promoted by 
Tymnet (a major packet switched network) and MNP is being 
promoted by Microcom (a major modem manufacturer). X.PC 
is being placed in the public domain and MNP requires a 
$2,500 licensing fee. 

X.PC is a subset of X.25, which is a CCITT standard for 
packet switched networks such as Tymnet. It is a full duplex 
asynchronous error correcting protocol that supports up to 15 
logical channels. X.PC is a Link Level protocol. The link 
level is one of the seven levels defined in the ISO / OSI 
(International Standards Organization Open Systems 
Interconnect) model. It maintains transparent full time 
automatic error correction during any communications session 
between two or more machines (right now this is limited to 
multiple PC's and/or machines on a Network that supports the 
X.PC protocol). X.PC protocol (as does MNP) groups bits of 
data into packets, does a high level statistical analysis of the 
packets (16 bit CRC) and transmits the results to the receiving 
end. The X.PC on the receiving end will also perform a 
statistical analysis of the received packet and if there has been 
an error in transmission it will request that the originator 
retransmit the packet. When connected to a Host Network that 
supports X.PC (such as Tymnet or Telenet) you can execute 
up to 15 different concurrent sessions (simultaneously talk to 
15 different Host Computers) with just one phone link. Each 
packet of data is encoded with both an address as to which 
computer system it is destined for and an address as to which 
system the packet originated from. 
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Programmer's Forum 
MacNosy Gets a Facelift 


MacWorkStation News 


Apple announced the availability of MacworkStation in 
the January developer newsletter in a small article. I think 
that this is what Scully has been talking about in some of his 
recent speeches when he mentions the Mac as a workstation. 
The only problem with the MacworkStation [a software 
program] is that instead of making it a public domain 
standard, Apple is licensing the source code for $1500 to 
"Interested" parties. My present feeling is that it would do 
more for Mac sales to sell the source code for a nominal fee 
then to license it. 

MacworkStation is a host based applications environment 
that enables host computer software to control the Macintosh 
user interface on a Macintosh. The idea behind the 
MacworkStation is that it's a way of writing applications on a 
host so it can utilize the graphic interface of the Macintosh. 
Just think, soon we will be able to log on to MAUG or 
Delphi and instead of emulating a teletype or a VT 100, we 
will have menus and windows, etc. 

MacworkStation consists of two parts, a protocol 
definition and a first implementation of that protocol. The 
protocol defines commands which are sent to the Macintosh, 
telling it what to do (put up a dialog box, etc). Events are 
defined to pass back to the host what is happening on the 
Macintosh. Note that much of what happens on the Mac need 
not be sent back to the host. The other part is a Macintosh 
Application that implements the protocol definition on a 
Macintosh. It is a generalized Macintosh application that is 
capable of being driven by an external process (the host). 
Unlike terminal emulation, the MacworkStation allows the 
host full access to the windows, pull down menus, dialogs, 
and other features of the Macintosh user interface. 

I hope this gives you enough information to whet your 
appetite. Just think of putting the Mac user interface on your 
favorite mainframe application. You will have to modifiy the 
mainframe end of it to send the appropiate commands to the 
Mac. But it might just make life pleasant for us grunts out 
there in hackerdom. 

For More information contact Apple Software licensing 
at (408) 973-4667 or write a letter to Scully requesting that 
MacworkStation be made a public standard. 


New MacNosy Version 2 
Over the past year MacNosy has helped many 
programmers learn about the Macintosh OS, and the workings 


of other Mac programs. Meeting some of my users at trade 
shows has been fun for me. Many of their suggestions have 
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been incorporated in Version 2 [denoted as V2] of MacNosy. 

The reasons for V2 of Nosy are the introduction of the 
128K ROM's, and the addition of features such as the context 
sensative symbol substitution discussed below. This was 
what I started with. By the time I was finsihed coding, the 
mini editor has been substantially extended to include displays 
of procedures by double clicking on a procedure name, and the 
ability to interactively create seperate, mergable comment files 
had been added. 


Nosy Does Windows! 


The introduction of the Mac user interface makes Nosy 
much easier to use. The illustration in figure 1 shows the 
procedure "browser" window partially obscured by the display 
of a procedure. The Display menu allows one to bring up 
windows containing the listing of a procedure, the references 
to any symbol, the complete reference list of system symbols 
referenced, the complete reference list of trapnames referenced, 
the listing of all the strings in the program, the list of code 
blocks in the program, etc. 


paran 
funRsit EQU 


"refs - copyROni28 


NU..' proc8 LINK — R6,9-$40 
vai-1086),R0 
MOVE.L param 1<A6), ioNameP tr (R0) 
; (RO|IOPB:ParaBIkPtr; aS 
DO, funRs! t (R6) 


SLELEELEEE 


Fig. 1 Windows supported 


Note that Nosy now lists the formal parameter list with 
the listing of a trap call, and for I/O calls, it knows that the 
register AO holds the address of the parameter block, so in 
between the defination of AO and the trap call it substitutes 
names of the structure variables. For a procedure that creates a 
Stack frame with a "LINK A6" instruction, references of the 
form -d(A6) are to local variables, and are named "vxx, n", and 
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those of the form d(A6) are the parameters "paraml", 
"param2",... , and if it is a function, the function result is 
called "funRslt". 


Other additions to the Window mode of Nosy are displays 
of information in its internal tables. They include a list of the 
structure names known to Nosy, lists of trapnames and their 
parameter lists, the names and values of the system global 
symbols, and a file listing most of constant definations for 
field values (event mask values and such). 


We eliminate the execution time associated with 10 
increment and test instructions at the cost of extra space by 
duplicating the assignment statement. 


Another interesting tidbit about the new ROM's are that 
they contain some 68020 instructions. Yes, Nosy knows 
about the 68020 instructions, and the FPU (68881) co- 
processor instructions. The new ROM's have been setup to 
run on a variety of machines as evidenced by some of the new 
EQU's. 


€ File Edit Display Reformat Misc Search Tables 


BOO Trapfigain 
B34 BtDskR fn 
B36 BootTmp8 
BSF T1Arbi trate 
B40 jDiskSel 
B44 jSendCmd 
B48 jDcdReset : m 
B4C LastSPExtra |E == untitled" 

B80 RMGRHiUars Some of the new symbols for <> 
BSE RomMapinsert| the 128K ROM's 

BOF TmpResLoad | ‘~~ 

BAO IntiSpec 

BA4 RMGRPerm 

BAS WordRedraw 

BAG SysFontFam 

BAS SysFontSize 

BAA MBarHeight 

BAC TESysJust 

BAE HiHeapMark 

BB2 SegHiEnable 

BB3 FDevDi sable 

BCO NewUnused 

BC2 Last_FOND 

BC6 FOND..!D 

BC8 App2Packs 

BES MA_ErrProc 

BEC MA_Super Tab 


Fig. 2 Symbols Displayed 
New ROM Secrets 


I have had a set of the new ROM's for a few weeks, and 
in addition to getting Nosy to disassemble them, I have made 
a few observations about the code in it. About 30K is devoted 
to resources, and to find out what they are use the "Rsrc map" 
list in window mode (Chicago font, WDEFO, etc). Other facts 
of interest are the methods used to speedup BlockMove and the 
QuickDraw routines. The code in Blockmove is unrolled, that 
is the loop body has been replicated a number of times to cut 
down on the number of increment and test instructions. The 
reason for this is that the 68000 used in the Mac is "bus 
limited", and anything one can do to cut down the number of 
instructions executed in a loop will speed it up. 


Consider the loop: 
for i := 1 to 20 do afi] := b[i]; 
by rewriting it as: 
for i := 1 to 20 by 2 do begin 
a[i]:»b[i]; afi+1] := b[i-1] 
end; 
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activateEvt 
networkEvt 


Last November I made a 
"ROM comments" version of 
Nosy available along with a 
comments file that Nosy read in 
and merged with the disassembly 
listings it produces. In V2 I 
have extended this capability so 
any file can be commented, and 
provided a way that one can 
interactively create the comment 
files in window mode. Another 
little goodie that was added in 
conjunction with the comment 
equates ) mode was to "annotate" 
"e MOVEQ  xx,DO instructions 
with a comment of the form "; 
err = name" if Nosy's symbol 
dictionary contained an error 
number for the value. 
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Copy De-protection Techniques 


Another use of Nosy is the location of copy protection 
code. To prefix this discussion, note that during manufacture 
(disk duplication), the duplicator writes the disk in a non- 
standard way by including non-standard data or address markers, 
or some other devious device so as to make the disk difficult to 
copy. During the execution of the program it checks the disk 
for the existance of this "mark", and if it finds it procedes 
normally. This checking code is usually refered to as copy 
protection code. 


Fortunately for us the program itself cannot be "marked", 
for if it were, the segment loader could not read it, so Nosy can 
read the file in, and if the copy protection code can be found, 
and eliminated, the program is still usable. A number of the 
facilities in Nosy are useful in the location of copy protection 
code. The reference maps, lists of the resources ("please insert 
master disk"), the "Strings" display, the Search Mark 
command, and the conVert address command. The Search 
Mark command searchs for references of the form "$DS ....." 
which are used to setup the Sony drivers for non-standard reads. 
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If the procedure that references that data area contains references 
to any of the disk driver variables, then Nosy displays the 
message "ahoy matey, x marks the spot (base of the copy 
protection code)", and lists the chain of procedures that call it. 
One can then inspect the chain of procedures to find a suitable 
place to patch the code. 


Trying to keep up with the changing copy protection 
methods is a never ending game, as evidenced by the frequent 
updates to Copy-To-Mac. I have sharpened some of the 
checks in Nosy so that it doesn't blow up or follow incorrect 
paths during the treewalk. This was done after I checked out 
some games, and found that they were putting garbage in the 
"CODE 0" segment. 


More coming... 


Other additions to V2 are the support of Desk accessories 
in Window mode, and the support of Switcher in all modes. 
Nosy is a continually evolving program to which I have been 
and will be adding bug fixs and new features. The current 
version of Nosy may be downloaded from my SIG on Delphi 
by those who have purchased it. At this time I am not sure 
what future directions Nosy will take, but some of the things 
under consideration are: 


- to add features to the window mode so as to make it easier to 
use 

- to make it into a debugger 

- to add a symbolic simulation of the register contents along 
with some more flow analysis so it handles languages 
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with register based calling sequences better, and produces 
a more informative reference map (knows the difference 
between Loads and Stores). 


[MacNosy version 2 is available through the MacTutor store 
for $85. -Ed] 


€ File Edit Display Reformat Misc Search Tables 
» -Trap refs map- E 


6E InitGraf proc4 


FE InitFonts copyRO 128 

112 InitWindows  copyROM128 

130 Ini tenus copuROn 128 

178 InitDialogs copuyROM128 
m os 0 procS 
EM OS 1 Close proc6 
B OS 2 Read proc? 
= oS 3 Write proc? 
os 8 Create proc 10 


BI os C GetFilelnfo procio 
M os D SetFilelnfo procio 
10 Al locate 


Peponi EERI proc 12 
— -Rsre Map- EEE 


Fig. 3 "TREF Wind" 
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Toolbox Notes 


On the nature of Pictures 


A Quick Note on Pictures 


This article has two puposes. The first is to more fully 
explain the information contained in Macintosh Technical 
Note #21; that is, the QuickDraw internal encoded picture 
format. The second bit of information concerns two problems 
which I have found relating to QuickDraw pictures. 

To begin, let's go over the process of creating a picture. 
When you call OpenPicture, QuickDraw allocates a new 
handle, stores some initial data there, sets the picSave field for 
the current port, calls HidePen, and returns the new handle. 
The initial data consists of the length, rectangle, version, and 
clipping region of the picture. 

When you then proceed to draw, calling QuickDraw with 
various artistic requests, QuickDraw notes that there is an 
open picture because of the valid picSave handle. Because of 
this, QuickDraw translates your request into its own picture 
shorthand, and appends this information to the picture data. 
The length information at the beginning of the picture data is 
increased to reflect the new data. Since HidePen had been 
called, none of this shows up on the screen. (Unless, of 
course, you have called ShowPen without a balancing call to 
HidePen.) 

Finally, you call ClosePicture which calls ShowPen, 
places an end-of-picture marker in the picture data, and sets the 
picSave field to NIL. 

Now, lets go through some picture data byte by byte. 
The first two bytes of information are the length, which 
represent the length of ALL of the data, including the length 
bytes themselves. Next are eight bytes (4 words/Integers) of 
rectangle information (top, left, bottom, right). This is the 
rectangle which was passed as the parameter to OpenPicture. 
Following this are the picture opcodes and their data. 

A picture opcode is a single byte which tells QuickDraw 
to do something, or how to interpret some amount of 
additional data. The length and composition of the data 
following the opcode depends on the opcode itself. The first 
opcode in a picture is always $11 which represents "Version". 
This opcode has one byte of data which represents the version 
number. Whenever QuickDraw encounters $11, it knows to 
treat the next byte as the version number, and to skip over it 
to get to the next opcode. Opcodes and their data are packed 
together. That is, immediately following an opcode and its 
data is the next opcode. 

After the version, there may be any number of 
QuickDraw opcodes. The last opcode in a picture is always 
$FF which stands for "End-of-Picture". Data after this opcode 
is ignored. (Under normal circumstances, there won't be any 
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further data.) 

If the picture was created in the usual manner (i.e. with 
OpenPicture instead of generating the picture data some other 
way) then the next opcode is $01 which is "ClipRgn". The 
data following this opcode is a region, the first word of which 
is the length of the region. Normally, it will look something 
like the data in Figure 1. When you call OpenPicture, the 
region is copied from the current port's clipping region. 


Version <= 11 


Clipping Region <4- 01 


01— version 1 


0A B» region size = 10 
00 07 00 07 00 CD 00 34 — region rectangle 
(7, 7, 205, 52) 


Figure #1 


Most of the opcodes are pretty straightforward. Some, 
however, could use a little explanation. Most of the verb- 
object calls have a corresponding verbSameobject call. The 
latter simply uses the last explicit data (be it a Rect, RRect, 
etc) from a prior call for its own argument. For example, if 
you wanted to do a paintRect (opcode $31) on a rectangle with 
coordinates (0,0,45,45) and then invertRect the same 
rectangle, the resultant picture data would look like that in 
Figure 2. 


paintRect «&- 31 00 00 00 00 00 2D 00 2D-P rectangle (0, 0, 45, 45) 


invertSameRect <- 3B 


Figure #2 


Instead of passing the fill pattern as an argument each 
time as in the QuickDraw call, pictures use the concept of a 
‘current’ fill pattern which the TechNote calls "thePat". (This 
is analagous to the current pen pattern.) To fill several Rects 
with the same pattern, there would be one opcode to set thePat 
($0A), and then several fillRect opcodes and their respective 
rectangles. (Figure 3). 


thePat = «0A 
filRect 4&34 
fillRect <4 34 
fillRect «€ 34 


AA 55 AA 55 AA 55 AA 55 ~® graypattem 

00 00 00 00 00 10 00 10 > rec (0, 0, 16, 16) 

00 00 00 2C 00 10 00 34 -9* rect (0, 44, 16, 52) 
00 30 00 41 00 45 00 SF -—» rect (48, 65, 69, 95) 


Figure #3 
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Because simple lines and text are so common, there are 
several versions of each so that QuickDraw can use the version 
that takes the least amount of space. Lines come in two sizes: 
regular and short. Short lines have vertical and horizontal 
lengths which can be represented by a single byte (-128 to 
127). The horizontal and vertical lengths are then used instead 
of the line endpoint. Both line and short line (opcodes $20 and 
$22) also include the starting endpoint. The remaining two 
line opcodes ($21 and $23) start the line from the current pen 
location, which could have been set by previous line or text 
drawing. 

If text is to be drawn only a short distance from the 
current pen location, QuickDraw uses opcodes $29, $2A, or 
$2B to move the pen horizontally, vertically, or both before 
drawing the text. If the starting location for the text is too 
distant to represent with single byte offsets, opcode $28 is 
used, and the actual point at which to draw the text is 
specified. 

The last ‘gotcha’, and the first problem I'd like to discuss 
both concern the SetOrigin call, which is opcode $0C. This 
opcode takes four bytes (two words/Integers) as arguments. 
BUT, the two words do not represent the actual origin that you 
specified with the SetOrigin call; Instead, they are the offset 
from the current origin to the new one. 

For example, if you were at origin (0,0) and you made a 
SetOrigin(15,10) call, the picture data would be $0C $00 $0F 
$00 $0A. More importantly, if you were in a situation where 
the origin was unknown, you might be inclined to call 
SetOrigin(0, 0) before performing any drawing. This can have 
some unexpected side effects. Consider the following scenario: 

Your code does not know where the origin is, so it calls 
SetOrigin(0, 0). Let us say that the origin was in fact at (15, 
10). QuickDraw would record an origin change of -15, -10 
($0C $FF $F1 $FF $F6). Then you do your drawing and close 
the picture. 

Now, since you didn't make any more SetOrigin calls, 
you know that the origin is at (0, 0), which is where you want 
it to be. So you call DrawPicture. QuickDraw would then 
come across the $0C opcode and changes the origin to (-15, - 
10), and your drawing would be in the wrong place! The Way 
to avoid this problem is to call SetOrigin before you open the 
picture, and again before you draw the picture. 

The technique of changing picture origins has a use, for 
example, in printing, when you want to draw a very large 
pictur’. You can simply originate different areas of the picture 
over the "printer paper' port and draw the picture. In this way, 
you can print your large picture on several pieces of paper. 
Moving pictures around is also a nice way to show different 
parts of a picture in response to a scroll bar; You only have to 
generate the display once, and just draw the picture with 
offsets based on the scroll bar values. 

But a common occurrance while doing this is to have the 
picture vanish when it is drawn at any location other than the 
one where it was created. The reason for this is simple but 
elusive. 

Recall that when you call OpenPicture, QuickDraw 
copies the clipping region of the port into the picture data. 
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Well, a newly created port has a very large clipping region, 
specifically, a rectangle with coordinates (-32767, -32767, 
32767, 32767). In hexadecimal, those coordinates translate to 
($8001, $8001, $7FFF, $7FFF). 

If you offset the picture rectangle just one pixel to the 
right, QuickDraw re-calculates all of the coordinates in the 
picture data, including those of the clipping region. But, if 
you add 1 to $8001, you get $8002 (which is -32766) and 1 4 
$7FFF is $8000 (decimal -32768). This leaves you with 
coordinates of (-32767, -32766, 32767, -32768) for the 
clipping rectangle. This is an empty rectangle because the 
right side is less than the left side. The whole picture gets 
clipped! 

The solution to this problem is as easy as the solution to 
the last one: Set your clipping region before you open your 
picture. You can keep the clipping region very large, but stay 
away from the values that come close to hex $8000. Such is 
life with finite mathematics. 

I hope this has helped to shed some light on your use of 
pictures. Used intelligently, they can save you from redrawing 
the same things again and again. As a side note, if you are 
interested in pictures and the LaserWriter, you should see 
TechNote #27: The MacDraw Picture Format. ae 

Ciao. 


609 


Macintosh Technical Notes é 


#21: Quickdraw's Internal Picture Definition 


See also: QuickDraw 
Programming in Assembly Language 


Written by: — Ginger Jernigan April 24, 1985 
This technote describes the internal format of the QuickDraw picture data structure. 


This technote describes the long awaited internal definition of the QuickDraw picture. The information 
given here is meant for DEBUGGING PURPOSES ONLY. It is NOT useful in writing your own picture 
bottleneck procedures. The reason is that if we add new objects to the picture definition, your program 
will not be able to operate on pictures created using standard QuickDraw. Your program will not know the 
size of the new objects and will, therefore, not be able to proceed past the new objects. (What this 


ultimately means is that pictures will not be downward compatible; you can't process a new picture with a 
old bottleneck proc.) 


Before listing the opcodes a little information is in order. An "opcode" is a number that DrawPicture, for 
example, uses to determine how to draw that particular object in the picture, and how much data is 
associated with it. The following list gives the opcode, the name of the object, the associated data, and 
the total size, in bytes, of the opcode and associated data. To better interpret the sizes, please refer to 
page 4 in Programming in Assembly Language. For types not described there, here is a quick list: 


opcode 1 byte 
point long 
0..255 1 byte 
-128..127 1 byte 
rect 8 bytes 
poly 11+ bytes 
region 10+ bytes 
fixed point number long 
pattern 8 bytes 


Each picture definition begins with a picsize (word), then a picframe (rect), and then the picture definition, 
which consists of a combination of the following opcodes: 


Opcode Name Additional Data Iota! Size (bytes) 
00 NOP none 1 

01 clipRgn rgn 1+rgn 
02 bkPat pattern 9 

03 txFont font (word) 3 

04 txFace face (byte) 2 

05 txMode mode (word) 3 

06 spExtra extra (fixed point) 5 

07 pnSize pnSize (point) 5 

08 pnMode mode (word) 3 

09 pnPat pattern 9 

0A thePat pattern 9 

0B ovSize point 5 

oC origin dh, dv (word) 5 

oD txSize size (word) 3 

0E fgColor color (long) 5 

oF bkColor color (long) 5 


610 © The Complete MacTutor, Vol. 2 


10 txRatio numer (point), denom (point) 9 
11 picVersion version (byte) 2 
20 line pnLoc ( point ), newPt ( point ) 9 
21 line from newPt ( point ) 5 
22 short line pnLoc ( point ), dh, dv (-128..127) 7 
23 short line from dh, dv (-128..127) 3 
28 long text txLoc ( point ), count (0..255), text 6+text 
29 DH text dh (0..255), count (0..255), text 3+text 
2A DV text dv (0..255), count (0..255), text 3+text 
2B DHDV text dh, dv (0..255), count (0..255), text 4+text 
30 frameRect rect 9 

31 paintRect rect 9 

32 eraseRect rect 9 

33 invertRect rect 9 

34 fillRect rect 9 

38 frameSameRect rect 1 

39 paintSameRect rect 1 

3A eraseSameRect rect 1 

3B invertSameRect rect 1 

3C fillSameRect rect 1 

40 frameRRect rect 9 

41 paintRRect rect 9 

42 eraseRRect rect 9 

43 invertRRect rect g 

44 fillRRect rect 9 

48 frameSameRRect rect 1 

49 paintSameRRect rect 1 

4A eraseSameRRect rect 1 

4B invertSameRRect rect 1 

4C fillSameRRect rect 1 

50 frameOval rect 9 

51 paintOval rect 9 

52 eraseOval rect 9 

53 invertOval rect 9 

54 fillOval rect 9 

58 frameSameOval rect 1 

59 paintSameOval rect 1 

5A eraseSameOval rect 1 

5B invertSameOval rect 1 

5C fillSameOval rect 1 

60 frameArc rect 9 

61 paintArc rect 9 

62 eraseArc rect 9 

63 invertArc rect 9 

64 fillArc rect 9 

68 frameSameArc rect 1 

69 paintSameArc rect 1 

6A eraseSameArc rect 1 

eB invertSameArc rect 1 

6C fillSameArc rect 1 
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70 framePoly poly 1+poly 

71 paintPoly poly 1+poly 

72 erasePoly poly 1+poly 

73 invertPoly poly 1+poly 

74 fillPoly poly 1+poly 

78 frameSamePoly (not yet implemented) 1 

79 paintSamePoly (not yet implemented) 1 

7A eraseSamePoly (not yet implemented) 1 

7B invertSamePoly (not yet implemented) 1 

7C fillSamePoly (not yet implemented) 1 

80 frameRgn rgn 1+rgn 

81 paintRgn rgn 1+rgn 

82 eraseRgn rgn 1+rgn 

83 invertRgn rgn 1+rgn 

84 fillRgn rgn 1+rgn 

88 frameSameRgn (not yet implemented) 1 

89 paintSameRgn (not yet implemented) 1 

8A eraseSameRgn (not yet implemented) 1 

8B invertSameRgn (not yet implemented) 1 

8C fillSameRgn (not yet implemented) 1 

90 BitsRect rowBytes, bounds, srcRect, dstRect, mode, 30+unpacked 
byteCount, unpacked bitData bitData 

91 BitsRgn rowBytes, bounds, srcRect, dstRect, mode,  30+rgn+ 
maskRgn, byteCount, unpacked bitData bitData 

98 PackBitsRect rowBytes, bounds, srcRect, dstRect, mode, —— 30«packed 
byteCount, packed bitData bitData 

99 PackBitsRgn rowBytes, bounds, srcRect, dstRect, mode, 30+rgn+ 
maskRgn, byteCount, packed bitData packed bitData 

AO shortComment kind(word) 3 

A1 longComment kind(word), size(word), data 5+data 

FF EndOfPicture none 1 
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The Electrical Mac + 


AppleTalk Connections 


The Appletalk Physical Layer 


This month I'm going to describe the physical (hardware) 
layer of the AppleTalk network protocol. I'll also respond to 
some mail and announce a new direction for this column, 
which I think everyone, including myself, will enjoy. 


Appletalk Protocol Architecture 


The AppleTalk protocol is based on a set of functional 
layers corresponding to the ISO (international Standards 
Organization) OSI (Open Systems Interconnection) reference 
model. Apple has provided a specific set of protocols for 
layers 1 through 5 (Physical, Data Link, Network, Transport, 
and Session) for the AppleTalk network. Being only an 
engineering type, I won't pretend to understand anything but 
layer 1, the physical layer, which is the electrical interface 
between devices. 


The Appletalk Physical Layer 


Each AppleTalk node has exactly one physical layer. It 
is here that the actual ones and zeros are passed between nodes 
after the data has been massaged into the correct format by the 
higher level layers. The electrical interface between nodes is 
an FMO encoded serial bit stream operating at 230.4 Kbits/sec 
over a transformer-isolated, multi-drop, shielded twisted-pair 
cable. [Note: This is the spec value. Actual value may vary 
slightly. See note at the end of this article. -Ed.] 

Data is encoded in SDLC (Serial Data Link Control) 
FMO format. SDLC defines the very low level data protocol 
and formats the data in a manner which assures that it can be 
recovered at the receiving node. FMO defines how ones and 
zeros are encoded. 


Figure 1 - Data encoding formats 
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Most low-speed serial communication encodes the ones 
and zeros in an NRZ (Non-Return to Zero) format. This is 
how the Macintosh normally talks to printers, modems, and 
the like. In NRZ encoding a high level represents a one and a 
low level represents a zero (Figure 1). With this encoding 
method clocking information is only available on bit-cell 
boundaries when a transition occurs. Because these transitions 
cannot be guaranteed when transmitting random data, a start 
bit is usually prefixed to the beginning and a stop bit is 
appended to the end of every data byte. The start and stop bit 
provide a known bit-transition to the receiving device, which 
it can use to synchronize its clock to the data. 

In FMO encoding, a transition occurs at the boundary of 
every bit-cell. If the bit is a zero, there is an additional 
transition in the middle of the cell (Figure 1). These 
transitions provide enough information for the clock to be 
recovered at the receiving device. 

The hardware required to support SDLC and FMO 
transmission, including the Phase-locked-loop used to recover 
the clock from the bit-cell boundary transitions, is all 
contained on the 8530 Serial Communications Controller 
(SCC) chip in the Macintosh. This makes switching between 
peripherals such as the printer and the AppleTalk network just 
a matter of reprogramming the control registers on the SCC 
(and much software, of course). 


Transmission Medium 


AppleTalk devices send and receive data over a single 
shielded, 22 AWG twisted-pair cable. Twisted-pair is adequate 
for the signalling rate and distances involved in AppleTalk and 
provides a very low-cost interconnect. Nodes are transformer 
coupled to the cable to provide DC isolation and reduce RFI 
and noise susceptibility. There can be a maximum of 32 
devices per bus and a total maximum cable length of 300 
meters. The cable must be terminated at each end with a 100 
ohm resistor for proper operation. 


Appletalk Connection Module 


Each node connects to the AppleTalk cable via a 
connection module. This module contains a transformer, two 
3-pin miniature DIN connectors each with a coupled switch, 
Some passive components and a DE-9 connector which mates 
to the Macintosh 512K (Does anyone but me care that there is 
no such thing as a DB-9 connector?) or DIN-8 connector on a 
Mac Plus. 

Figure 2 is a schematic representation of an AppleTalk 
connection module. J1 and J2 are the 3-pin miniature DIN 
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connectors which are coupled to switches connected to R2. 
This resistor automatically provides the 100 ohm bus 
termination if there is only one cable plugged into the module. 
R1 is a drain for the cable shield and R5 and C1 form a high 
pass filter to reduce EMI and isolate the grounds of AppleTalk 
devices from each other. R3 and R4 increase the noise 
immunity of the receivers. 


The connection module is a completely passive device. If 
a node should fail it will not affect the integrity of the network 
as long as it fails either high or low and is not broadcasting 
garbage. The node is driven directly from the outputs of the 
Macintosh RS-422 drivers and feeds directly through R3 and 
R4 to the RS-422 receivers. No additional active circuitry is 
required to connect a Macintosh to the AppleTalk network. 

The coupling transformer is a 1:1 turns ratio transformer 
with the primary wound as two windings of 32 AWG wire in 
series with one wound below the secondary and one above it 
on a Siemans B65651-K000-R030 core (Figure 3). 


MAIL 
The mail Ive received generally asks one of two 
questions: 1) "How can I modify my Macintosh to do 2" 
and 2) "How can I interface my Macintosh to 2", My 


answer to the first question is it is my policy (not necessarily 
MacTutor's) that I will not encourage anyone to modify their 
Mac. 
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My answer to the second 
question hopefully will make up for 
the first, for all you hardware hackers 
out there. In keeping with the 
Macintosh concept of the serial ports 
and the AppleTalk network creating a 
"Virtual Bus" I will soon have an 
article on constructing a "Virtual 
Card" which will plug into this bus. 
Once you have the "Virtual Card" it 
can be expanded to add whatever type 
of peripheral device you'd like. 

Starting next month, this 
column will take a more hands-on 
approach to hardware. We'll start 
building things instead of just 
talking about them. If you have any 
projects you'd like to see done, send a 
letter to me care of MacTutor. 


Letters From Our Readers 


SCC Timing Off 
Dave M. Gaylee-Lincer 
Rainin Research Group 

Emeryville, CA 


The SCC clock timing as described in the Oct 1985 
MacTutor differs somewhat in practice. I have observed the 
following: 


1. The measured frequency is 3.672 Mhz when measured with 
a frequency counter. 


2. I examined the waveform over a number of cycles and found 
that the timing goes shorter and longer. When I examined 
the waveform in more detail, I found that in 64 clocks of the 
15.6672 Mhz, that there were 15 SCC clocks. This reatio is 
not 4.25 to 1 as specified in the documentation, but works 
out to 4.266666666. 


This changes several things that could be important to 
third party developers (like ourselves) in that the Appletalk 
baud rate is now: 3.672 Mhz / 16 = 229.5 Kbaud. 

This is approximately .4% different from the electrical 
specifications given in the book Inside Appletalk by Apple 
Computer Inc. [Spec is 230.4 Kbaud.] This is OK if you are 
precisely at nominal, but it reduces the margin if you, perhaps, 
aren't perfect. 


Power Supply Problems 
Dave Roberts 
Santa Barbara, CA 


Recently I had my 128K Mac power supply blow out. A 
friend of mine's Mac also had it's power supply fail. I have 
also heard of several other people's power supplies failing. 
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MacTutor has printed several letters of people with similar 
experiences. Now just what is the deal with the power supply? 
I have had an Apple II+ for over 4 years and have not had so 
much as a hick-up out of it. What is the deal with the Mac? 
For almost $100 that is kind of an expensive thing to happen. 
The store that I got it fixed at delayed getting mine fixed 
because the power supplies they had gotten in from Apple 
were D.O.A. You would think with all that talent they could 
give it a power supply that wouldn't fail so often! 

[Perhaps we can cover the power supply circuit in a 
future column and point out some of it's short comings. -Ed] 

Hardware Review Wanted 
M. Joseph El-Sayed 

Montreal, Quebec 
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You should, little suggestion here, put out a bi-annual 
(or something around that frequency) hardware product review. 
The review should be based on compiled user opinion and may 
be tests you guy's ran (if you have the time). By the way, 
some roses, your Journal is certainly THE Mac-mag to read. I 
have access to subscriptions of MacWorld (yech), MacUser 
(Better), and MacNibble (the other mag to look at). Anyways, 
keep up the definitly superior work. 

[Hardware reviews are expensive, (you have to have the 
hardware!) but we'll see what we can do in that area. -Ed] 

Serial Port Changes in Mac Plus? 
David Smith 
MacTutor 

I have a question for the hardware column. Recently I 
bought a Spinwriter 8810 printer from Nec along with their 
Macintosh kit (cable and software). The software was done by 
Assimilation Process under contract and is very similar to 
their printer utilities. It modifies the Imagewriter Driver file to 
work in draft mode with the Nec printer. The cable and 
software work perfectly on a 512K Mac using all versions of 
the Imagewriter file. However, when I try it on my Mac Plus, | 
the printer buffer fills up and an overflow error stops printing. 
Only the gnd, handshake, recieve and transmit lines are being 
used from the printer. We have also discovered that several 
computer stores are selling Mac DB-9 cables to DIN-8 
connectors that are wired backwards, so beware! Help? 


e 


tas. 
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Resource Roundup 
All About Resource Editors 


Choosing and Using a Resource Editor 


This article is the first of several articles on using 
resources when developing a Macintosh application. This 
month, we'll look at the structure of resources and how the 
two resource editors available from Apple can be used to free 
you from RMaker. 

If you're just getting started, you can also use the 
resource editors to understand how a typical application is put 
together. The study of actual applications can provide a 
valuable education in Macintosh development, much as an 
MBA student studies the case histories of existing businesses. 

The article will describe the general structure of resources, 
and how to choose between the various resource-building tools 
available to the developer. 


Inescapable Resources 


If you've gone very far with program development on the 
Mac, then by now you know it's impossible to write a 
program of any size without a thorough understanding of 
resources. Although some might consider them a needless 
extra step of in program development, they do make it easier 
to make certain types of changes in a program — particularly 
now, two years after the Mac's introduction, when there are 
two complete Resource Editors available. One of these editors 
can, in fact, be adapted to edit just about any sort of data 
structure. 

The proper use of resources also provides a notable 
benefit over traditional approaches when dealing with the 
international marketplace. If all the text seen by a user is 
contained in the application's resources, then your program 
can be translated to run in a foreign country — without 
making your source code available to someone else. 

This article is inteded to provided a brief introduction to 
resources. The standard reference on the topic is, of course, 
Inside Macintosh, under the chapter “The Resource Manager: 
A Programmer's Guide." From a survey I've taken of 
developers, it usually takes several readings before most of the 
details sink in. 

Once you understand the general resource concepts, you 
still don't know how to use specific resources. They're 
described in the respective chapters descripting the 
corresponding Toolbox libraries, such as the Menu Manager, 
Font Manager, and so on. 


The Structure of Resources 


One of the most controversial aspect of the Macintosh 
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design is that every file contains two “forks”, or sections: the 
data fork and the resource fork. 1 say controversial, because 
most files you'll find on your Mac normally have only one 
component or the other. For example, the MacWrite file that 
contains this article has only a data fork; the MacWrite 
application, the System and the Finder all have only resources. 
(Other computers have the same sorts of files, but there's 
usually a bit somewhere that indicates whether the file has 
program or data.) 

One of the few examples I know of with both data and 
resources is a MacTerminal document. You can access the 
data received in a terminal session by editing the data fork with 
MacWrite. Or, you can reclaim the terminal's configuration 
(CNFG^) from MacTerminal in the resource fork. For most 
purposes, you can assume that the data fork contains 
unformatted ASCII text, which is the most common, but by 
no means only, situation. 

Resources, however, should not just be considered a fancy 
name for what you'll find in the .EXE file of your IBM PC 
(sorry) or the a.out of your UNIX system. Resources are the 
relational database of Macintosh systems programming: not 
only do they provide a way of storing information necessary to 
run a program, but they also provide a standard hierarchy for 
that information. 

Every resource has three identifiers that serve to make it 
unique. The first idenitifer (or “key”, if you want a database 
talisman) is, of course, resource file that contains the resource. 
Traditional repositories of these are the System file and 
individual applications. The Resource Manager does allow 
combining resources from several files, as will be discussed 
later. 

The second identifier is a four-character ASCII resource 
type. Normally, this consists of four capital letters, as in 
‘MENU’, ‘WIND’, and ‘CNTL’ for menus, windows, and 
controls, respectively. However, a few resource names end in 
a space or number sign, such as ‘STR ' and ‘STR#’, which 
refer to strings and a list of strings. 

Third, each resource within a given type and file must 
have a unique 16-bit integer, referred to as the resource ID. In 
most cases, resources that you assign should be numbered 
between 128 and 32,767. Resources in the range 0 to 127 are 
reserved for system (Apple-defined) usages; negative id's are 
generally used by resources that are nested within other 
resources, such as in a desk accessory. 

Alternately, each resource of a given type can have a 
specific name, as for a type font. Although the resource id 
must always be unique, a unique resource name can be used as 
the third key. Usually the id or name is used to reference a 
given type, but not both. 
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Fig. 1 Resource Overview 


In most cases, the layout of all resources of a given type 
will follow the same explicit set of rules, no matter what file 
or id they have. Unfortunately, there are a few types that do 
not, such as ‘PREC’ and ‘INTL’. 

The overall structure of the resource fork of a file is 
represented by Figure 1. Each resource fork contains both the 


actual resource data, and the resource map, which is nothing 
more than a index to where each resource is located. As 


suggested by the illustration, each resource of a given type and 
id (or name) can be found by tracing the links from the 
beginning of the resource map. The links are represented as an 
offset within the resource map (2 bytes) or within the resource 
data (3 bytes), depending on where the referenced data lies. 
Not shown are the resources which reference other 
resources, usually by resource ID and an implied resource type. 
For example, alert and dialog template resources (used by the 
dialog manager routines) will normally reference a 
corresponding item list. Item lists can, in turn, reference 
control, icons, or QuickDraw pictures. And if you want a non- 
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standard control, menu, or window, you would reference a 
"CDEF', '*MDEF' or *WDEF' resource from within a ‘CNTL’, 
‘MENU’ or 'WIND' resource. 

The custom is that related resources (e.g., dialogs and 
item lists) are numbered the same, but this is only a 
convention, not a requirement of the resource manager. It 
does, however, make it easier for you (or a foreign marketeer) 
to modify national or personal preferences. 


Accessing Resources Within a Program 


Normally, a particular resource will be referenced through 
the appropriate manager routine, e.g., the Menu Manager, 
Window Manager, or Control Manager. Most such routines 
only require the resource ID, since they already know the 
resource type to look for when searching the open resource 
files of your application. 

However, you can always get at an arbitrary resource on a 
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particular file as follows (all examples are given for Megamax 
C): 


resfilno = OpenResFile("System"); 
if (resfilno >= 0) 
reshandle = GetResource(RT_ICON, rsrcid); 


else 

MyQuit(ResError()); 

NOTE: If youre just getting started with 
resources, or you've recently switched languages, 


be aware that there are two possible approaches 
for passing resource type arguments. For those 
using assembler, some C's, and languages that 
closely follow Lisa Pascal, the resource type will 


usually be a 32-bit word with the 4 ASCII 
characters stored high-to-low. Such types can be 
given in hexadecimal, although some compilers 


allow you to show it as a character string. 

However, most languages define a series of 2 
or more characters as a string, which is a 32-bit 
pointer to the 4 characters. In Megamax C, for 
example, any resource type argument is passed as 
a string (pointer), and the interface routine fetches 
the referenced ASCII word before calling the 
toolbox. 

To tell the two forms apart, look at the menu 
setup routine of the skeleton application supplied 
by the vendor. It wil probably contain a 
statement to merge desk accessories into the 
Apple menu that looks like one of the following: 


AddResMenu(myMenus[appleMenu], ‘DRVR’); 
AddResMenu(myMenus[appleMenu], 0x44525652); 
AddResMenu(myMenus[appleMenu], "DRVR"); 


The form used by the second argument to 
AddResMenu is either by value (first two forms) 
or by pointer (third form). This is the same form 
you must use in any other routine that expects a 
resource type. To make it easy to switch between 
different programming systems, you should use a 
symbolic definition, such as the corresponding C 
declarations: 


#define RT ICON ‘ICON’ 
#define RT_CON 0x49434F4E 
#define RT ICON "ICON" 


Resource Attributes 


We've already seen how every resource has: 
e Four-letter resource type 
e 16-bit integer resource id 
* (Optional) resource name, as a Pascal string 
Each resource also has a 16-bit word holding resource 
attributes. However, only the low-order byte is used; six of 
these bits are used as boolean flags, as shown by their 
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reserved 

resChanged (don't use) 
resPreload 
resProtected 


Figure 2: Resource attributes byte 


symbolic names in Figure 2. 

For a new application, you would typically define only 
three of these attributes. If resPreload is set, the resource to 
be read into memory when your program launches; you would 
normally want all your menus declared this way, for example. 
The resPurgeable flag allows the resource to be purged 
(removed) any time more memory is needed, while 
resLocked prevents the resource from being relocated or 
purged, thus avoiding handle-dereferencing memory problems. 

You can gain the resource attribute for any resource you 
have a handle for by a simple call: 


attrs = GetResAttrs(reshandle); 


Although the resource type remains fixed, you can change 
the resource ID, name, or attributes while your program is 
running. A good example of this would be the 


SetReslInfo(reshandle, ID, name); 
SetResAttrs(reshandle, attrs) 


You should distinguish between the original copy of the 
resource in the resource file, and the copy that is currently in 
memory. Setting (or resetting) most of these attributes will 
only have an effect once the changed resource has been written 
to disk and then re-read. (The exception is resProtected, 
which takes effect immediately). Instead, if you need to 
protect the copy of the resource in memory, you should use 
the customary memory manager routines HLock and 
HNoPurge. 

The one attribute you don't change directly is 
resChanged. Instead, you call ChangedResource and 
then the resource manager will assure that the modified 
resource is written out at some point. To be on the safe side, 
you may want to force the changes to be written immediately: 


ChangedResource(reshandle); 
WriteResource(reshandle); 
UpdateResFile(resfilno); 


If you want to change the length of the resource — such 
as to lengthen a string field — there is no easy way to do it. 
Instead, you have the create a new copy of the resource and 
remove the old copy: 


newresh « NewHandle(newsize); 


O The Complete MacTutor, Vol. 2 


BlockMove(*reshandle, *newresh, oldsize); 
/* Now put the new data in ... 

*/ 

RmveResource(reshandle); 
AddResource(newresh, restype, ID, name); 
DisposHandle(reshandle); 

reshandle = newresh; 


If you’re just getting started, you should note that it’s 
generally very dangerous to pass a dereferenced handle as an 
argument, because a heap compaction would move the blocks 
pointed to by the pointer. However, if you have“Trap List”, 
published by Apple, you can look up BlockMove and see 
that it doesn’t call any memory manager routines, so there’s 
no need to HLock the two handles. 


(Ed 
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Resource-Building Tools 


Any professional development system for the Mac will 
be shipped with some sort of resource compiler, such as the 
RMaker of the MDS system, which is also shipped on 
several other systems. It takes the definition of a resource in a 
line-oriented, symbolic form to produce the binary version 
stored in the resource fork of a file. 

A complete description of the Lisa Pascal resource 
compiler is contained in the Inside Macintosh chapter "Putting 
Together a Macintosh Application." The input format for 
other compilers is usually somewhat different, so double-check 
the manual that came with your system, after reading Inside 
Mac. Also, some resource types recognized by the Lisa 
Workshop compiler must be simulated under other compilers, 
as discussed later. 


Figure 4: Choice of 'ICON' resources 
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The standard resource compiler format consists of: 
* Resource type 
* Resource name (optional) 
* Resource ID 
* Resource attributes 
* Type-specific resource data 

For example, an ICON is a 32-by-32 pixel resource that 
used for symbols, such as the disk shown when you swap 
disks (if you own, or ever owned a 128K Mac, this should be 
a familiar sight by now!) 

To build an Icon with a resource compiler, you would 
define the bit map as a pattern, typically a series of 32 
integers, each 32 bits wide. Thus, an icon might be defined 
by the following (the numbers are shown four per line for 
compactness): 


Type ICON 
,0(32) » no name, ID=0, purgeable at any time 

FFFFFFFF 807FFFFF 807FFFFF 807FFFFF 
807FFFFF 807F807F 887E001F 887COO0F 
88781C07 80781C07 80701C03 80701C03 
80701C03 80701003 80701C03 80701C03 
80701C03 80701C03 80701C03 80701C03 
87F00003 81F01C03 81F01C07 81F01C07 
81FO0000F 81E0001F 8F80007F 81FFFFFF 
81FFFFFF 81FFFFFF 81FFFFFF FFFFFFFF 


Development is made easier, however, if you have one of 
two resource editors written at Apple and distributed through 
various informal channels. You should not confuse the two, 
which have differing strengths and design points. 

REdit was written by Gerard Schutten in Apple's 
Netherlands office for translating programs to foreign 
languages. Release 1.0, dated March 1985, was given to 
developers in the Software Supplement of July (“May”) 1985, 
and is contained on the MacTutor Utility Disk No. 1. 

The Jack-in-the-Box icon ResEdit was prototyped by 
Rony Sebok and Steve Capps in Cupertino and is now being 
completed by Gene Pope of Apple. It has been floating 
around in pre-release form for a year and a half now. At press 
time, the latest version available was Release 1.0D7 from the 
March 1986 (officially, "December 1985”) Software 
Supplement. ($25 from Apple) Most of the versions 
released thus far have a tendency to crash, some more than 
others. Whichever ResEdit you use, be sure to take Apple's 
advice, and don't attempt to edit any file that you haven't 
backed up. 


Choosing a Resource Editor 


How do you choose between the resource editors? Figure 
3 shows a list of the standard resource types, and a subjective 
evaluation of which is best for each type. 

REdit is oriented towards customizing an application for 
a particular country. As a result, it is designed for use by 
quiche-eating marketting types, rather than Real Programmers. 
REdit makes easy for just about anyone to modify certain 
types of resources by changing resources likely to contain text 
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Icon iD = 0 from System : 


Figure 5: Editing an 'ICON' resource with ResEdit 


or other nationalisms. 

However, some of its idiot-proof features can get in the 
way. Perhaps the most annoying is that you can't open a 
resource file that's in use, in case you might want to modify 
it. This means that even if you just want to look at a resource 
in the System file, you have to load a spare disk, because 
you're not allowed to open the boot system. 

REdit also contains a built-in decompiler for those types, 
which builds a file compatible with the Lisa Workshop 
resource compiler. You can use this to study the structure of 
an application, for further modification or imitation. 

On the other hand, ResEdit was written for use by 
programmers. It is designed to completely replace the use of a 
resource compiler and, in its current edition, does just that. 

For most types, ResEdit presents data comparable to the 
line-oriented RMaker format, displayed in a series of editable 
text fields within a dialog box. Cursors, fonts, icons and 
patterns can be edited in a "Fat Bits" format, while alerts, 
dialogs and windows can be sized and positioned either 
graphically or through a dialog box. 

Note that for most types where you have a choice, REdit 
is preferred, primarily because it has a cleaner graphical 
interface. For example, REdit uses graphical interface to set 
size and position of the dialog box and allows you to easily go 
through all the items in Dialog ITem List (‘DITL’). Each 
item can be resized or repositioned both graphically or through 
a dialog box. 

One futher area where REdit has an advantage is in text 
fields, both in item lists and in string resources. REdit allows 
6 lines of data, while ResEdit allows 3 lines for item lists, and 
2 lines for ‘STR ' and ‘STR#’ resources. This limitation is 
particularly annoying when editing alerts, such as "Printing in 
progress. To cancel printing..." 

On the other hand, ResEdit allows you to set the alert- 
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specific parameters that determine whether a particular alert 
will beep or display a window. And it also gives you more 
flexibility in adding new items or changing the item types for 
dialog item lists. 

Overall, once you've set up your dialogs and alerts, 
you'll probably find yourself using ResEdit more often, 
because it supports the common resource types. I have one 
development floppy with the public domain RamStart set to 
load the system, finder, ResEdit and a text editor. 


Using the Resource Editors 


To get a feel for the structure of an application, grab a 
resource editor and a spare boot disk. There are more resource 
examples in a typical boot disk than in the 1800* pages of 
Inside Macintosh. 

Once you've booted the editor, use Open... in the File 
menu to open the System file. (If you're using REdit, it 
CAN'T be the one on the boot volume). This will create a 
window with a list of resource types, in text for ResEdit, and 
iconic for REdit. In the case of REdit, unknown types are 
shown by a question mark. 

Open the type ‘ICON’ and you will get a list of resources 
of that type. If you've used ResEdit, your choices will 
resemble the window shown in Figure 4. 

Double-click the icon resource that you want to edit. 
Both resource editors will open a new window and offer a Fat 
Bits-style display, such as shown in Figure 5. If you make 
any changes, they will be reflected the next time you save the 
resource file. 

Once you select a specific resource, the Get Info menu 
option of ResEdit allows you to change the resource ID, 
resource name, and resource attributes. Be careful not to set 
the resource ID to the same value as other resources of the 
same type. A unique ID will be automatically assigned, when 
you create a new resource. 

Both resource editors know how to edit only certain types 
of resources. Unknown types will be shown as a series of 
bytes in hexadecimal for ResEdit, and in hex and ASCII for 
REdit. You can also force this format in ResEdit for any 
resource by using Open general. 


Resource Type vs. Creator 


Apple has a list of standard resource types that should be 
used only for their official purpose, and also reserves names 
containing only lower-case letters. Most of the standard types 
are shown in Figure 4; for more information, see Macintosh 
Technical Note $32, available from Apple. 

Other than these restrictions, you're free to invent your 
own resource type names for whatever purpose you want. For 
example, you must invent a new type for an application's 
signature. This is a four-letter code that MUST be unique 
across all the disks currently loaded on your Mac. For 
commercial software, this unique signature is assigned by 
Apple; otherwise, just watch out for duplicates. 

Normally, the signature will show up in two places: 
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MacWrite 4.5 Text-Only 


MACA MACA 
APPL TEXT 


| holds signature 
resource of 
type 'MACA' 


Creator: 
File Type: 


MACA 
WORD 


Figure 6: Three types of MacWrite files 


* In the creator field of the application and any documents it 
creates; 
e As a resource in the application. 


Figure 6 shows the relationship of the fields for 
MacWrite, a representative application. There are three types 
of files that can be found with a creator of ‘MACA’, while 
each has a different file type. 

There will always be at least one file with the creator 
matching the signature — the one with file type 'APPL',the 
MacWrite application itself. Note that only the application 
contains the ‘MACA’ resource; by convention, this resource 
contains a version string. 

The other two files with the creator ‘MACA’ are 
documents used by MacWrite. The two files are text-only 
documents (type ‘TEXT’) and documents with MacWrite 
formatting controls (type ‘WORD’). The Get Info item of 
ResEdit allows you to specify both creator and file type fields. 
When using RMaker, the first eight characters of the second 
signficant (non-comment) line give the file type (‘APPL’) and 
creator (‘MACA’). 


The Bundled Solution 


All of the information for all three file types is obtained 
from the application — such as the icon for the corresponding 
type, and which application to run when the document is 
opened. This relationship is defined by a ‘BNDL’ resource, 
which in turn references other resource types.can be edited 
using ResEdit. 

Although bundling would normally be the last step of 
developing an application, building a bundle adds a satisfying 
flair to your prototype application, and it's quite easy to do 
with ResEdit. The process of bundling is described in the 
"Structure of a Macintosh Application" chapter of Inside 
Macintosh, but we can use ResEdit and MacWrite to study an 
actual example. 

Figure 7 shows the MacWrite bundle with the actual 
ResEdit prompts underlined, and the corresponding fields to 
the prompts. For ease of understanding, the (icon and file type) 
values referenced by the bundles are shown, although they're 
not actually included in the bundle. Instead, the icons are 
contained in a ‘ICN#’ referenced by the bundle, while the 
‘FREF’ contains the corresponding file types for these icons. 

The figure also shows two conflicting conventions for 
describing resource lists. “numTypes” is the number of 
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: OwnerName: MACA 
| ownerID; 0 
| numTypes: 2 


| type: ICN# 
: #ofthistype: 2 
localID rsrcID CS 
0 123—> 


| type: FREF 
| Hofthistype: 2 


localID rsrcID (File Type) 
128 APPL 


1 122 WORD 
130 TYPE 


Figure 7: Structure of the MacWrite ‘BNDL’ resource 


resource types in the bundle, while “# of this type” is one less 
than the number. 

You can copy your bundle from this, because most will 
be identical to this. The only exception is that your 
applications might have only one document type, so that the 
"$t of this type" would then be 1. 


Special-purpose Resource Tools 


In addition to the resource compiler and two general-use 
resource editors, there are also two resource editors designed for 
specific purposes. 

One is designed for one of the more unusual and 
important resource types: 'INTL'. This resource type is used 
to isolate the names of weekdays and months, the currency 
symbol, date order, and other country-specific information. 

There are only two resources of this type, which are 
contained in the System file and have reserved ID's of 0 and 1. 
Unfortunately, the format of these two resources is different. 
However, REdit can edit these two resources, because it has 
been designed to treat the two ID's differently. This is an 
excellent way to see what differences are supported, if you 
have access to a System file customized for another country. 

This assumes, however, you know what the appropriate 
values are for the country in question. For major countries, 
the easiest way to get these values is with the Localizer 
utility. It sets the international resources in the System file 
for the United Kingdom, France, Spain, Italy, Germany, 
Sweden, Belgium and the Netherlands. Note that although the 
language is the same, the U.K. and Ireland formats are different 
from the U.S., primarily in the currency and order of the date. 
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For the New World, Localizer supports Quebec (French- 
speaking Canada), while lumping English-speaking Canadians 
in with the U.S. and Latin America with Spain. At the same 
time, it can also change the keyboard mapping to target the 
specific countries, although it obviously won’t do much for 
the keycap labels. Localizer was included on the “May 85" 
edition of the Software Supplement. 

There’s also a resource editor designed specifically 
forediting dialogs called Dialog Creator, developed by 
Michael Bayer of Apple Canada. It allows you to create and 
modify a dialog specification, including adding new items and 
changing existing items. It also allows you to see and edit the 
definition in RMaker source form, as well as saving the 
compiled resources to the application. The original April 
1985 version was limited to only 25 items per dialog, but the 
version from the “December 1985” supplement supports 60 
items, a realistic limit. On the other hand, Dialog Creator has 
a modal approach that takes a little getting used to. 


Conclusion 


The handyman’s motto of “the right tool for any job” 
applies to the building of resources. Each of the tools has an 
application (excuse the pun) to the construction of a 
Macintosh program. 

Using a resource compiler and its line-oriented descriptive 
file provides the best permanent documentation. It also allows 
you to use published program examples as the starting point, 
such as those provided in MacTutor. 

However, many developers find that the Edit-Compile- 
Test process is too slow for developing new applications. 
Instead, a resource editor, particularly one that provides a 
graphical interface, allows you to see the results of the 
changes as they’re being made. 

ResEdit is the best for this purpose. However, keep both 
REdit and Dialog Creator, particularly if you’re working on 
dialog boxes. 


Commonly used by Applications 


Code Description Use (orexample) ResEdit REdit 
ALRT Alert box Alert template yes* yes 
BNDL Bundle Buiding application yes 
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CODE Program User application — — 
DITL Item list Dialogs, alerts yes | yes 
DLOG Dialog box Dialog template yes | yes 
FREF File reference to related document yes 

ICN# Iconandmask Application, docs yes yes 


MENU Menu lists Menus, menu items yes  yes* 
SIZE Switcher size — Minimum memory yes 

STR String Text, file names yes  yes* 
WIND Window Window template — yes  yes* 


Primarily used by System 
CURS 16x 16cursor (Watch, I-beam) yes 


DRVR Driver (Desk accesories) 1 

FCMT Finder comment Desktop “Get Info” yes — 
FKEY Func key Cmd-shift routines — — 
FOND Font family Font manager yes 
FONT Font All user fonts yes 


INIT Initialization When system loaded 

INTL International Country-specific t yes 
LAYO Finderlayour Desktop display 

PACK Code Package Code libraries — — 


PAT 8x8 pattern (Scroll bar) yes 

PAT# Pattern list (MacPaint) yes 
Rarely Used 

CDEF Custom control — — 

CNTL Control Defaults, scroll bars f 


FWID Font width 
ICON 32x32icon (Author's face) yes yes 
MBAR Menu bar Complete menu set —  — 
MDEF Custom menu (keypad, patterns)  — — 
PREC Printer custom — — 


PICT QD picture (Help screen) t t 
STR# String list Messages yes  yes* 
WDEF Custom window (unusual shape) — — 
+ Limited capability A 

* Preferred editor | Ry ! 


Figure 3: Choosing between resource editors 
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MidWest Report 


Chicago Visited & TMON Re-Visited! 


Darrin Adler's User Area for TMON 


Some of you may remember my review of TMON from 
ICOM Simulations, Inc. in the September, 1985 issue of 
MacTutor. If you do, you should be aware that I said two 
things which were incorrect, for which I apologize to ICOM 
and MacTutor's readers. 

First, I said that TMON was the name of the first 
machine language monitor that I ever used. In fact, the name 
of the monitor was T-BUG, which was a terrible little tape- 
based monitor for the Model I TRS-80. My apologies to 
ICOM for associating their product with this primitive piece 
of code. 

Secondly, and more importantly, I said that I thought that 
it would be a while before anyone came up with a way to 
improve upon TMON's pre-defined user area routines. The 
folks at ICOM have done their level best to make a liar out of 
me. 

If the name Darin Adler rings a bell, it's probably because 
he's a co-author of Déjà Vu, the innovative Macintosh 
adventure game, and is the author of the SkipFinder desk 
accessory, which is one of the more elegant Finder bypassing 
tools around. SkipFinder is in the public domain, as is the 
Extended User Area that Darin wrote, which is the subject of 
this article. [The Extended User Area is available on the source 
code disk for this issue. Latest Version is 665. -Ed.] 

Now its probably as good a time as any to write this 
disclaimer: the TMON Extended User Area was written by 
Darin Adler in a capacity not directly related to ICOM 
Simulations. The Extended User Area is not a product of 
ICOM Simulations, is not sold by ICOM Simulations, and 
most importantly, is not supported by ICOM Simulations. If 
you want a copy of the Extended User Area, you can get it 
from MacTutor, me, Darin Adler, and the Delphi and 
CompuServe information systems. If you need help with the 
Extended User Area, your best bet is to write to Darin Adler at 
the address given in the source file. Failing that, you can ask 
me. Incidentally, the Extended User Area is not completely 
documented anywhere other than here, so if there's something 
that I don't cover well enough, you'll have to talk to Darin or 
myself [Write Paul care of MacTutor. -Ed.] 

The Extended User Area came to me on a disk which 
includes three files: PackIt II, EUA 662.pit, and EUA 662 
Source.pit. PackIt II is the second version of the de facto 
standard Macintosh file packer program. The program is 
Shareware, so please send the requested contribution. EUA 
662.pit is a combination of User Area, EUA ð, and 
PatchTMON. User Area is the ready-to-load user area file for 
TMON; EUA ð is some skimpy (very skimpy) 
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documentation, and PatchTMON is a little program that fixes 
TMON so that it will allow user areas as large as EUA 
version 662. EUA 662 Source.pit contains a lot of files 
which collectively make up the EUA 662 MDS source code 
(“for the curious and ambitious ones," says Jay Zipnick of 
ICOM). 

Features of this new User Area 


The Extended User Area (hereafter called EUA for the sake 
of my fingers) goes quite a bit above and beyond the call of 
duty for a TMON user area. It's so big that TMON must be 
patched to accomodate it. Among other things, it patches 
TMON itself to do things like show the application's screen 
behind TMON's windows and eliminate the schizophrenic 
cursor (there are no longer two separate cursor positions, one 
for the application and one for the monitor; the cursor is an 
entity distinct from any operational mode). 

The EUA also adds some nice little features like 
implementing the _Debugger trap (the lack of which in the 
standard TMON Darin called an "oversight" when I talked to 
him), embedding the System.MAP globals in the user area (no 
more reserving space for the label table and loading the .MAP 
file), and making the distinction between what the system 
global TopMem says and what it really is (this appears to be 
crucial for proper operation under Switcher). 

These, however, are just the icing on the cake - the 
"sexy" features, to borrow an idiom from The Soul of a New 
Machine. The real guts of the EUA lie in the things that you 
can see - new features used from the "User" mode within 
TMON. 

Since the "E" in EUA stands for "Extended," you may 
have concluded that Darin has added on to the existing user 
area routines. This is true, and I won't bore you by rehashing 
what the existing routines do. Rather, I'll concentrate on the 
new ones. 

First of all, there is the "Toggle screens" function. Since 
Darin has added several new functions to the user area, he had 
to provide the capability of getting to them all. Since the user 
window has no scroll bar (another oversight, says Darin), he 
had to split the functions into three separate screens. This 
function, which is present on all screens, is the mechanism for 
moving among the three sets of functions. 


Templates for Key Data Structures 
"Template" is a major new function which, when given 
the address of a data structure that it knows about, displays the 


names and contents of the pertinent parts of the data structure. 
For example, you can give the WindowRecord template the 
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address of a WindowRecord and it will tell you the window's 
bounds, title, whether or not it's visible, highlighted, or has a 
close box, and a lot more. The other data structures that 
Template recognizes are ControlRecords, TERecords, and 
ParamBlocks. 

"Stack addresses" simply displays the addresses on the 
stack from the top down. If the address is within a 
recognizable distance of a label, this function will display the 
label and its offset also. 


Tracing Stack Activity 


"Stack crawl" is a fascinating function. It's based on the 
fact that local variables for Macintosh programs are generally 
built around the LINK instruction using the A6 register. 
These local frames can also be nested; that is, any new frame 
points to the one that was there before it. Stack crawl threads 
its way through these local variable frames on the stack, 
showing you exactly where in the code these frames were 
created (i.e., where the program was executing when you 
entered the monitor). Since this function follows the linked 
list on the stack all the way to the end, it can show you a 
blow-by-blow account of what has executed up to the point 
that you entered the monitor. Keep this in mind the next time 
you enter TMON because of a 68000 exception! 

The "Click mouse outside TMON" function is simply 
the "Show screen" function renamed, since the application 
screen can now be seen behind TMON's windows. 

The "Launch" function purportedly allows you to either 
launch the Finder or relaunch the current application. Both 
fail miserably in version 662. Darin is working on a fix. 

"Shut Down" reboots the system. The disks can be 
ejected before restarting or they can be left in. 

"Windows" is one of those things that really should have 
been a part of TMON to start with. It allows you to define 
which windows you want to be open when you enter the 
monitor. The way this is done is a) enter TMON, preferably 
by double clicking, b) open your favorite windows, anchor 
them, and position them, c) open the user window and place 
the cursor by the windows function (it's on the second screen). 
Now you need to decide whether you want the user window 
open or not. If you do, choose 0, otherwise choose 1. Then 
exit to the TMON application (the dialog with all of the 
options). Press the "configure" button and save the user area 
back out to disk. Now whenever you launch TMON with that 
user area the windows that you selected will already be up and 
waiting for you (as will whatever choices you have made for 
such user area functions as Trap Intercept, Trap Signal, etc.) 


Does it follow the Rules? 


Now for the real biggie, the function that makes Darin's 
EUA completely worthwhile, even with the bugs that haven't 
been completely worked out. It's called Trap Discipline. 

A bit of history is in order. There is an application called 
"Discipline" which was written by Steve Capps for the 
purpose of helping him avoid obvious bugs in new versions 
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of the Finder. (Unfortunately for Mr. Capps, even Discipline 
can't find logic errors). Mr. Capps' version of Discipline was 
really intended for his own personal use, and from what I 
understand of the program from Darin - I don't actually have a 
copy - it reflects that fact in that it only checks some of the 
more esoteric and obscure elements of some of the more 
esoteric and obscure toolbox traps and OS traps. 

Darin took the concept, extended it greatly, and made it 
an integral part of the EUA. Like most trap functions, Trap 
Discipline takes a trap number or range and optionally a PC 
address or range. As the trap and PC conditions are met, an 
appropriate routine is called which makes sure that the 
parameters to that trap are valid. If they are not, TMON is 
entered and a message displayed, which is usually nothing 
more than a question mark followed by the data type of the bad 
data ("handle," "string," "rect," etc.). Sometimes Discipline 
goes into more detail - "NIL address," it might say. The PC 
will be pointing to the trap that Discipline had problems with. 
Be aware that the fact that Discipline didn't think a parameter 
was kosher doesn't mean that it isn't. In particular, Discipline 
may think that a rect "makes no sense" - it may be off the 
screen or something. This may or may not be a bug in the 
use of a rect - it depends upon the application. 

There are two styles of Discipline - strict and lenient. 
Darin recommends using strict discipline during program 
development and using lenient to look for idiosyncracies and 
bugs in existing programs. 


Surprise! Apple's Stuff Flunks! 


Its interesting to note that when I tell TMON to 
discipline all traps, some of Apple's own code doesn't make 
the grade. The MDEF code in particular seems to be prone to 
bad strings on a  StringWidth trap. Continuing execution, 
though, seems to have no ill effect. Trying to use Discipline 
on MacWrite results in a great number of Discipline entries to 
TMON and, eventually, in a crashed system! MacWrite breaks 
a lot of Mac programming rules and seems to still have a great 
number of insects lurking in its innards. 

Speaking of bugs lurking, using Discipline on ResEdit 
prototype #0 (the old ResEdit) reveals why ResEdit seems to 
run out of memory so quickly. For some reason, after closing 
the window for a particular resource, ResEdit #0 tries to 
_HUnlock an invalid handle. Obviously, the real handle is 
still lying around in the heap, locked up tight as a drum. 
Open enough windows on individual resources, close them, 
and violá - you have a Mac filled with handles that should 
have been unlocked so as to make heap compaction possible. 
They weren't, so the result is heap fragmentation, rapid out-of- 
memory conditions, and a lot of headaches for ResEdit #0 
users. Give yourself a break and use a newer ResEdit 
(1.0D11 seems to be current as of this writing; its not 
without its flakeys, either, but that's another story). 

Of course, another important EUA feature is that it goes 
a good way toward making TMON function properly with the 
new ROMs. It's not solid yet, and not all of the new ROM 
routines are named, and certainly not all of the low RAM 
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globals are named, but it's a good start. 
New Super Debugger on the Way 


Note: TMON with EUA is NOT the last word on Mac+ 
debuggers. I have it from a reliable source that ICOM 
Simulations has planned and is working on a new debugger for 
the Mac+ that will completely blow away everything that has 
come before it, including the current version of TMON. In 
fact, it's been suggested that a lot of the ideas implemented in 
EUA are experimental versions of things that will be standard 
in this new debugger! 

All of this is starting to sound rather unreal, isn't it? My 
vote for the most useful developer's tool on the Macintosh 
goes to TMON with Darin's EUA hands down. If you are a 
512K Mac programmer and you are programming in a 
language which generates 68000 machine code as its end result 
(as opposed to M-CODE; direct, indirect, or token threaded 
code; or straight interpreted systems - sorry MacModula-2, 
MacFORTH, Neon, and MS-BASIC programmers), you owe 
it to yourself, now more than ever, to be using TMON and 
Darin Adler's Extended User Area. 

On the down side, the documentation for the EUA is 
sketchy. There are a few bugs in version 662. Darin is also a 
prolific programmer. I got a copy of his EUA without Trap 
Discipline from him, and within a matter of less than three 
weeks I got a copy that had it. Since this is public domain 
software and is Darin's pet project, it is subject to change 
without notice and it may change at an alarming rate. I will 
keep informed of any further upgrades to TMON and Darin's 
EUA, and I will pass that information along to you. 

Now, if you don't own TMON, aren't you just a little 
jealous? [If so, you can get it from MacTutor's mail order 
store. TMON is a commercial product, only the EUA is 


shareware. -Ed.] 
a E E 


MacExpo '86 Chicago Report 


It was an interesting event. 


MacExpo '86 took place from ten in the morning Friday, 
April 25 to five in the afternoon Sunday, April 27 (with very 
brief periodic breaks to do things like eat and sleep - not all in 
attendance were programmers). 

Ironically enough, I was at the expo as a private concern - 

I had no idea at all as to whether MacTutor would be there in 

an official capacity or not. I decided that even if MacTutor 
wasn't an exhibitor that I could write about what I saw and 
therefore deserved at least press Standing. Apparently the 
organizers agreed; I received my press kit and ID badge with no 
problems. 

The first booth to appear upon entering the hall was the 
MACazines, which makes sense; they were in large part 
responsible for this expo taking place. 

I decided that the best way to tackle the floor was simply 
to wander around until I saw something interesting. 
Fortunately, one of the first things to catch my eye was a 
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banner with our name and logo on it (I had never really 
realized how distinctive our Mac Tutor icon is until I saw that)! 
At that point I had the first of what was to become a fairly 
common experience: seeing the face behind the voice on the 
phone. I had the pleasure of meeting Laura and Mona, two 
ladies whose names should be familiar to most of our 
readership. For those who don't know, Laura is Laura Smith, 
the manager of MacTutor, and Mona is Mona Crompton, our 
circulation manager. David Smith, our ever-dedicated 
publisher/editor-in-chief, was not able to be present because - 

what else? - he was busily preparing the May issue for 
publication. 

Having met the other MacTutor folks, I started to look 
around the floor. Here are some people and things that I saw. 

Kriya Systems was there to show off Neon version 1.5 
and the new Neon assembler. I did get the 1.5 upgrade but I 
did not get the assembler; I was on a pretty tight budget. 
There are a lot of things to like about the upgrade: more of the 
System source is there, and there are some new classes to do 
even more neat things (2D and 3D arrays, for example) and 
some new utilities, like a decompiler. 

Odesta had demos of the various versions of Helix every 
hour on the hour. I'm not sure that I remember all of the 
Helix family, but I remember Helix, Double Helix, Multi- 
User Helix, and RemoteHelix. The Helix system in whatever 
form is a very impressive package, and I recommend it very 
highly for anyone who needs a very powerful yet very easy to 
use database system. 

It seems like everyone and his mother has a SCSI hard 
disk out for the Mac+ now. It's good from a purchasing 
perspective; the competition drives down prices. I was very 
impressed with Mirror Technologies MagNet 20. It's a small, 
narrow, thin drive that sits alongside the Mac and, of course, 
runs from the SCSI port of the Mac+. It's small, fast, and 
completely silent. At the show it was $995.00. 

Levco was there, and of course the big deal was the 
Prodigy 4, Levco's 68020/math coprocessor/4 meg RAM 
upgrade. This is a power user's dream; a System with this 
upgrade is faster than a VAX 11/785, prompting Eric Zocher 
of Silicon Beach Software (all together now: Tah tah tah tah 
tah, tah tah tah (gh tah) to refer to it as the "MacVAX." The 
upgrade is supported by at least two development systems: 
Consulair's Mac C and Palo Alto Shipping's Mach 1. 

Silicon Beach Software was there, and they've been busy. 
World Builder, the system used to create Enchanted Scepters, 
was on display and is due to be released this summer. 
Likewise SuperPaint, a combination MacPaint/MacDraw 
program that looks very, very nice. 

Ann Arbor Softworks was there to show FullPaint, their 
plug-in replacement for MacPaint. Seems like everyone's 
trying to outdo Bill Atkinson these days. With MacPaint's 
limitations and the unbundling of it with the Mac+, I suppose 
it was inevitable. FullPaint is an ambitious paint program, 
but it lacks SuperPaint's hybrid paint/draw capabilities. 
However, FullPaint is available now, whereas SuperPaint 
isnt. [It's also protected, a consideration that could be 
discouraging for a paint type utility. -Ed.] 
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VIP - Very Important Program? 


Mainstay was there with their new product line, and quite 
a line it is! Mainstay has established themselves in the field 
of writing small, useful tools like Turbo Download, Type 
Now, and Disk Ranger. The most exciting thing that I saw 
from Mainstay is a system called VIP, which stands for Visual 
Interactive Programming. VIP is a structured interpreted 
programming system which is graphical in nature. Program 
constructs are entered by clicking on tools on a palette a 1a 
MacPaint. Assignment operators, looping constructs, even 
toolbox access is represented graphically in almost a flowchart 
form. Once the program is laid out, it can be run and/or 
debugged. This system is also slated for a not-too-distant 
release date. [Watch for a MacTutor column on VIP in a future 
issue. -Ed.] 

Palo Alto Shipping was present Their Mach 1 
development system is at version 1.25, and it incorporates 
some new optimizations, particularly for the DO LOOP 
construct, that make an already fast system run like greased 
lightning. If you have any interest in Macintosh FORTH 
systems at all, and don't mind not having the object-oriented 
capabilities of Neon, then order Mach 1 now, because there are 
rumors of a future rise in price. 

"The Rest of Us," a huge Chicago-area Mac users' group, 
was there. Not only were they there, but they had two very 
big names in the shareware business with them: Scott 
Watson, whose remarkable Red Ryder terminal program has 
developed a reputation that borders on mythology, and Don 
Brown, author of the MockPackage and numerous other 
shareware offerings. 

Red Ryder is now at version 9.1 (or at least it was 
yesterday - it went from 9.0 to 9.1 at the show, and I had to 
trade up because of that) There have been numerous 
enhancements to Red lately, not the least of which is Mac+ 
and HFS compatibility. VT100 and VTS2 emulation are 
there, folks, as is support for CompuServe's B protocol file 
transfers. People at the show could buy "pre-registered" copies 
of Red for the same old $40.00 price that Scott has always 
asked for. Scott also gave a seminar on shareware (talking 
primarily about Red, of course) and mentioned briefly the 
enhanced graphics driver, called Nautilus, that Red contains. 
Hes working on some tools to make Nautilus useful to 
everyone; when those are done hell document Nautilus 
completely. Sounds exciting! 


Construct your own BBS! 


Paying for Red now gets you something new from Scott: 
Red Ryder Host, which Scott refers to as "a BBS construction 
set." It's not a BBS; it's a set of tools that let the user create a 
custom BBS with multiple security levels, upload/download, 
multiple message centers, and so forth (are you listening, 
Rusty)? This is available only to registered Red owners and is 
NOT shareware - any non-registered Red owners operating a 
Red Ryder Host-created BBS are in mucho trouble. 
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Unfortunately, Host takes up two disks all by its lonesome 
(Scott says it includes over seventy pages of documentation) 
and required too much time/expense to include with the Red 
packages at the show (it would have been a four disk package 
all together). So, registered owners need to download Host 
from GEnie, which is where all of Scott's support is handled 
now. 
D2 Software was there showing MacSpin, the three 
dimensional statistical analysis program that has been drawing 
rave reviews. I'm afraid that statistics of any kind is out of 
my league, so I can't comment on the program myself. 

Enabling Technologies was present to show Easy 3D, the 
novel three dimensional modeling program. This one shades 
very quickly and has different “light sources" for a variety of 
shadowing capabilities. If you need to draw shaded three 
dimensional images, this looks like a great system. 

There were many, many other exhibitors and products 
there, and it is not my intention to slight anyone by not going 
into detail about them or their product. These descriptions 
here are just things that popped into my memory after the 
weekend was over and I had some time on my hands with 
which to nurse the strep throat that I developed and to write 
about what I remember happening. 


Friends of MacTutor 


Random notes: Meeting people. Jerry Daniels of the 
Mac Underground... Doug Clapp... Sitting with Silicon 
Beach Software at the exhibitors party as they received an 
informal award for best graphics product (SuperPaint) and 
listening to the author muse about adding neat new features 
like cut and paste support... Meeting John Pence of Affinity, 
the author of Tempo... Making the acquaintance of Eric 
Zocher from Silicon Beach and looking at World Builder and 
SuperPaint - and a behind the scenes look at Lightspeed C 
(wow!)... Meeting Scott Watson and beginning to understand 
his software philosophy - and why Red Ryder is making it 
come true, plus getting a one sentence glowing review of 
Lightspeed C - so glowing that it can't be repeated in a family- 
oriented magazine like MacTutor... Running into Jay Zipnick 
of ICOM Simulations, trying to move TMON on his behalf, 
and seeing a sneak preview of Uninvited, the successor to Déja 
Vu - if you liked Déja Vu, you'll love Uninvited... 

And, most important of all, meeting the many MacTutor 
subscribers who keep us going and keep us on our toes. 
Some are developers for major Mac software firms, others are 
hackers digging into the machine for the pure joy of it. Either 
way, the "atta boys" and the constructive criticisms are much 
appreciated. Writing for a magazine is a very anonymous 
profession, and its wonderful to meet the people who are 
reading your material. So thanks, guys. 

Well, I think I'll wrap this up now. I've got a lot of stuff 
to look at from the expo, including a flowcharting program 
that looks very promising, Neon 1.5, Mach1 1.25, and soon 
some other things which haven't been released yet. Stay 
tuned! Enjoy, my 

Paul F. Snively Sol 
(~*~ o. 5 oN 
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Nosy News 


The Art of Code Re-construction 


In this special article by the famous industry guru Steve Jasek, 
author of MacNosy, we get the inside Scoop on the inner 
workings of Nosy and how to use it to best advantage. Since 
Steve is famous for his brief documentation, these pearls of 
wisdom will be most valuable, but be warned: this is not for 
the faint hearted, as Steve's technical background in compiler 
design is clearly evident. -Ed. 


Sniffing Around with MacNosy 

As I sit here pecking away on my Mac, it is mid June. 
Nosy 2.099 has been finalized and 2.1 is in progress. Most of 
the features I discuss in this article are in 2.099, and the rest 
will appear in 2.1 which will ship in J uly. 

For starters, I'd like to try and answer some rhetorical 
questions such as: 

What is and why use Nosy, and what advantage does it 
Offer over other methods of obtaining information about 
programs? 

Hypertext for programmmers 

Nosy is a fancy disassembler with extensive reference 
map (Hypertext for programmmers?) and symbol substitution 
facilities that verges on being a de-compiler. Nosy can be 
used to obtain information about any program or resource that 
consists of 68000 native code. It does not handle Pcode, 
Mcode, etc. It can be used to obtain accurate and informative 
listings of the ROM (64 or 128K), resources on the system 
file, etc. It knows about the special structure of DRVR's 
(desk accessories) and PDEF's. It can create '.asm' files that 
can be fed into the MDS assembler. Later on this year it will 
be modified so that its output will be compatable with the 
MPW (Macintosh Programmer's Workshop) assembler. 

Because it subdivides the program up into procedures and 
data blocks, and creates reference maps for those symbols, one 
is able to analyze what the program is doing without having 
to execute it in many cases. When Nosy is used in 
conjunction with a ".map" file produced by a Linker or the 
debug symbols left in the code by most compilers one can use 
it as a "source" level cross reference map facility for one's own 
program. This can aid in tracking down bugs or making 
modifications to the program. [Note: TML, LightSpeed and 
Consulair support debug code in their compilation that aids 
Nosy. -Ed.] 

You Didn't Read this Section in MacTutor! 

In the same vein one can use Nosy to locate and analyze 
copy protection code. Modifications scheduled for V2.1 will 
let one disassemble CODE segments from programs that are 
running in another partition under Switcher. This will allow 
one to analyze copy protection code that has been encrypted in 
the disk file copy of the program. The fun thing about this 


© The Complete MacTutor, Vol. 2 


Steve Jasik 


Menlo Park, CA 
Mr. Nosy 


mod is that no program that is Switcher friendly will be able 
to protect against this form of copy protection analysis as they 
have no real way of knowing that Nosy is looking at them, 
and one will not need to make a debugger initially active, so 
programs that check for the presence of one, and then blowup 
will be hoodwinked. Note that some programs check for the 
presence of a debugger by inspecting the interrupt vector 
address's ( 0 to $100) to ensure that they reference ROM and 
blowup if they don't. 

Given the proper order of things in Starting up Switcher, 
Nosy and the program to be analyzed, Nosy will temporarly 
put any debugger to "sleep" so any other program cannot 
detect its presence. After one has patched the code in the 
program that disables the debugger, one can wake up the 
debugger, and use a combination of it and Nosy to locate and 
disable the copy protection code. I am temped to offer a prize 
to anyone who can devise a method that cannot be cracked by 
Nosy. [Ouch! -Ed.] 

More Coming... 

While I am in the process of teaching Nosy how to 
locate the CODE segments of running programs, I thought it 
would also be nice if Nosy was fixed so that it could 
disassemble arbitrarly large programs in 512K. 

My motives for adding this facility at this time are two. 
Firstly to allow the analysis of programs that would not fit 
into memory, and secondly I will be needing more space for 
tables in order to do global data flow analysis soon. 

You can also use Nosy for code inspection of your own 
application. As Nosy grows in size, I use Nosy on itself to 
look at the code generated by Lisa Pascal to see what code it is 
generating for a given sequence of statements, and when the 
code looks like it can be trimmed by choosing another 
sequence I rewrite it by using the type-casting facility, etc. 

Other reasons for using Nosy are to learn about 68000 
code, and how Macintosh applications are structured. The 
Nosy disk contains a number of interesting examples, 
including a fast Shell sort which is extensively commented, 
and describes my assembly language coding techniques. 


Compilers and Data Flow Analysis 

Nosy makes use of a variety of techniques that are similar 
to those used in compilers. For example, it has a variety of 
symbol tables, which use the address of the symbol instead of 
the name as the primary lookup key. It also uses control and 
data flow analysis to obtain information about the structure of 
the program, but first some terminology and review. 
Control flow analysis, which concerns itself with the flow 
of execution in a program, is familiar to many 
programmmers. 
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Call Graph of a simple Program 


program 
begin 

call B; 
end; 


Fig. 1 Call Graph 


A Basic block consists of a sequence of contigious 
statements such that if any statement in the block is executed, 
all are. Basic blocks end prior to an active label or after a 
jump instruction which would be representated in a higher 
level language by an if, case or goto statment. In a flow 
graph basic blocks are the nodes (the circles) and the edges are 
the possible flow paths of execution. (See fig. 1 for a diagram 
of a Basic Block). The usual conventions are that flow is from 
top to bottom with backward branchs representated as curved 
lines. The ground symbol represents the return statement. In 
the example below we have a simple for loop with a side 
branch that the programmmer would have written as: 


for j := Low to upLim do 


if a[j] <> O then B[j] := Bij] / alj); 
Return 


In the process of analyzing the code, compilers will 
invent labels for basic blocks that are the target of branch 
instructions, which is why I rewrote the code in the diagram in 
fig. 2. 


J :z Low; 


1:if a[j]] = O then goto 2; 


B[J] := B[J] / a[J]; 


2: J:2 J +1; 
IF J < upLim then goto 1; 


Flow Graph for a simple procdeure 


Fig. 2 Flow Graph for above example 


The process of collecting the flow of control information 
is a fairly simple one. Analyzing it to find the loops in the 
program, etc is slightly more complicated, but straightforward. 
When one does this on an inter-procedural level the resulting 
graph is called the “program call graph." Building a 
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complete call graph in the presence of procedures that accept 
parameters as arguments is somewhat more difficult. For 
compilers this is no real problem, as very few of them do inter- 
procedural optimization. For Nosy it represents a real 
problem, as initially it does not know what the arguments to 
user procedures are or their types. To date, my solution to the 
problem has been to let the user supply the information 
manually by the Review data and IsProc commands which 
are discussed in the next section. 

Before we can discuss how Nosy can complete the call 
graph automatically, I need to say a bit about data flow 
analysis, which is the process of collecting information about 
the way variables are used in a program. In order to do 
effective global optimization or de-compilation one has to 
collect both control and data flow information. The exact 
sequence of events is that the control flow information for a 
procedure and the data flow tables for the basic blocks in a 
procedure are built first. Then the control flow information is 
used to "solve" the data flow equations globally. The 
questions that an optimizing compiler will be able to answer 
with the data flow information are: 

What variables are not defined in the loop? The 
resulting set of expressions that use the variables are 
candidates for code motion out of the loop, etc. 

When does the value of a variable that is assigned to a 
register in a loop have to be placed in memory prior to exit (is 
Live on exit) from a loop or more generally a basic block? 
This is usually called the Live/Dead information. 

The information that a compiler collects for each 
variable/array in a basic block is called the use/def info, and 
consists of three bits for each variable; used in the block, 
defined in the block and used before definitation. From this 
and the control flow information one can develop the 
Live/Dead information. 

For most real languages, the problem of building the 
use/def tables is compounded by alaising of names due to 
the presence of array references, or pointer variables which 
may point to the same location in memory at run-time. Most 
of you are familiar with the problem, but without giving it a 
name. As a simple example of alaising, consider the 
following sequence where p is a pointer to an integer: 


p:=addr(i); (pis equivalenced or alaised to i} 

X := A[i]; 

p^ :-2; 

y := ALi]; {would it be valid to change this to y := x; 7? } 


Given the above code it would be imprudent for an 
optimizing compiler to replace the second reference to A[i] ] 
with x, for example, since the value of i has been changed 
directly in memory, and thus the programmer expects x and y 
will have different values! 

The primary effect of alaising is to inhibit code 
optimization. Compilers for languages such as C, with its 
weak typing of pointer variables have a difficult time in 
producing good code in the presence of stores to pointer based 
variables. 
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,~refs - 3/PRINTOAT 
20DC: ‘.:' data410 DC.N $13A 


; «RO/srcPtr, Al/destPtr:Ptr; DO/byteCount:Size» 
LEA globSOCR5), AO 

LEA globS3(AS). A1 

JSR APPENDST 

LEA EBIEEND,eO ; len= 2 

LEA globS3¢AS)>, A1 

JSR APPENDST 

JSR PRINTLIN 


Fig. 3 Review Data command in window mode 


Now back to Nosy. Another form of data flow problem 
concerns itself with determining the type of a variable based 
on its usage. This is the problem that Nosy has to solve if it 
is to automatically recognize procedural parameters and 
propagate this information back to the calls so that all code 
blocks will be recognized as such. To do this Nosy must 
perform a symbolic simulation of the 68000 registers and 
Stack as it disassembles the instructions to determine the usage 
of variables in a basic block, and that it keep enough control 
flow information around so it can propagate the type 
information out of the procedure and back to the caller. | 
Started to work on this problem a few weeks ago and got 
sidetracked by the needs of my documentator to complete 
window mode so that we could document the visable parts of 
Nosy. With luck I'll get back to it in time to show it off at 
the August MacWorld show. 

AS a final note in this section, the topics discussed here 
are relatively old hat, [! -Ed.] and one can find a more complete 
discussion of optimization and flow analysis in chapter 10 of 
the "Red Dragon" book by Aho, Sethi & Ullman (Addison- 
Wesley). It's correct title is "Compilers, Principles, 
techniques and Tools". It is a standard text book for Comp 
Sci undergraduates. I recommend its purchase to anyone who 
is interested in understanding the structure of compilers. 


Using Nosy to reformat Data 


Nosy analyzes a program by walking the tree of 
procedures to build the program call graph. At present, the 
treewalk is a one pass algorithm which recognizes the 
procedure entry points by their references in JSR's. Procedures 
that are passed as parameters (a common practice in Mac 
programs) are not recognized as code unless there is an explicit 
reference to them in a JSR. This creates the situation that not 
all the code is exposed by Nosy. To get around this problem, 
I created the Review data command which lets one inspect the 
data blocks, and reformat them as one wishs. 

Now I have converted the Review data command to 
window mode, one can see the context in which a data block is 
referenced and do a more inteligent job of redefining the format 
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of the block, be it code or otherwise. 

When the Review data command is selected, Nosy 
cleans up the desktop by closing all the active windows except 
for the "-Notes-" window which is a scratchpad for your and 
Nosy's use. It then puts up a modeless dialog window for 
keyboard entry at the top of the screen, a menu window below 
it, a "-Data Blk-" window which displays the data block to be 
modified, and a '-Usesz" window with a display of a reference 
to the data block, if any exists. In Review data mode, all 
keyboard input is directed to the command window. 

The illustration in figure 3 [RevDAT 1] shows the label 
data410 passed to APPENDST which we might guess to be a 
String concatenate routine. With this information, it is easy 
to surmise that data410 is a Pascal String. If one wanted to 
find out what APPENDST did, all one has to do is double 
click on the name and ctl-D to bring up a display of it. The 
only reason for reformatting all the data blocks in a program 
is if one wanted to "Cut and Paste" the code in it into another 
application. 

An alternative way of reformatting data blocks in 
window mode is to mark them as procedure entry points with 
the "Is Proc" command. Data blocks marked as "IsProc" 
will be treated as the entry point to a procedure on all 
subsequent treewalks. In some programs, such as the PTCH 
resource in the System file, which contains the patchs to the 
ROM, it is easier to mark the data labels with the IsProc 
command then it is via Review data. Figure 4 [Ptch IsProc] 
illustrates the use of this command. 

One hi-lites a data label, and then selects the "Is Proc" 
command. As an aside, note that most of the System Globals 
that begin with a lowercase j contain a pointer to the address 
of a routine, so one may /sproc them with impunity. 

Case Statment Analysis 

Another reason that all the code may not be apparant to 
Nosy is because of case statements that it cannot understand. 
The Case Jumps display (Fig. 5 next page) lets you determine 
which jumps are causing Nosy problems. The "Link Jump to 
Table" command lets you specify information about the jump 
so that Nosy can process it correctly the next time a treewalk 
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Fig. 4 ISProc command 
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s[ E - Case Jumps- 

case*  jmpLaddr tbi_addr bias n-branch info 
1 =01006 166 0 0 0 
2 =040027E8 =040027F8 0 18 2481 JUMP 
3 =0100619C =0 1006 1A0 0 16 1C81 JUMP 
4 =01001C4C =01001CSE 0 16 2481 JUMP 
9 =0 100 19FR 0 -? 2481 JUMP 
6 =010015E6 z010015F6 O -1 2481 JUMP 


mystery case stmts have n-branch <= 0 or tbl addr = 
Hilite the jmp_addr & ctI-D to display the containi 


Fig. 5 Case Jumps 


is done. In figure 6 [Lnk JMP2] we see that the offending 
case jump table consists entirely of negative entries so Nosy 
has declined to set the length of the table at 7, which can be 
done with the dialog box in the upper left hand corner of the 
display. The basic problem is that during the treewalk when 
Nosy inspects the jump instruction, it does not know the 
length of the data block. Because all the jump table entries are 
negative, it is not sure where the table ends. When a jump 
table has at least one positive entry, Nosy can use that entry 
to determine the length of the jump table based on the 
assumption that code for the cases immediately follow the 
jump table. 

The table format of this case statement is JUMPP, 
which means that the the jump table is to be interpreted as 
program relocatable offsets to procedure labels. The JUMPC 
format defines a case or switch table to be a set of jumps to 
com labels (code which is branched to by a JMP, BRA or 
Bxx instruction). The normal format for a case table which 
consists of jumps to labels local to a procedure is JUMPL. 
It is sometimes useful to break up a big procedure with a case 
table into smaller procedures by changing the format of the 
case table from JUMPL to JUMPC. 
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Fig. 6 Correcting Table Jumps 


Closing thoughts 


In writing the above section I was temped to go back, 
reinspect my algorithms and see if I couldn't automatically 
recognize the case discussed in the first example. After all, it 
is easier to solve the problem once in the product as opposed 
to have to explain it many times to others. Unfortunately 
Nosy does need human help in recognizing some patterns, and 
those of us who use it should be familiar with techniques for 
reformatting data, etc. Some time ago a famous industrial 
engineer, Peter Denning told an audience of Twist Drill 
manufacturers that what their customers wanted was not drills, 
but holes. I remind myself that what you want is information 
without hassle, and to that end I will continue to improve 
Nosy so the de-compilation process runs more on automatic, 
and less on manual. [Please help support Steve's efforts in our 
behalf by both BUYING Nosy and spreading the WORD, not 
the DISK. -Ed.] 
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Technical Notes 
66020 Programming 
Considerations 


Dave McClain 
Senior Engineer 
The WSM Group 
The WSM Group provides a Hyper-C and asm 
development system for the Macintosh with the unique feature 
that the complete source code to the system is also available at 
a very reasonable price. Contact them at (602) 298-7910. This 
tech note is valuable as we canticipate the next Mac family of 
68020 based systems. 


As one of a fortunate class of Macintosh programmers, I 
have had the enjoyable opportunity to run a 68020 MPU chip 
in my Macintosh. Initial investigations show, however, that 
a number of incompatibilities exist between the 68000 and the 
68020 in spite of the claim that the 68020 is "upward 
compatible" with its ancestors. This paper addresses a few of 
these of these claims and offers some suggestions for the 
future, as well as some patches for the present... 


Welcome to the Future 


The exceptional processing of the 68020 is considerably 
more complex than that of the 68000. The stack frame 
produced as a result of calling a TRAP or receiving an 
interrupt includes a format word beneath the saved PC (and 
possibly a bunch more information as well.). The RTE 
instruction of the 68020 expects to see this format word. 

Many of us have written code which saves the current 
Status register contents on the stack on entry to a called 
routine, and as a shortcut, we execute an RTE which restores 
the old status register and performs an effective RTS all at 
once...well, it used to.. Now, with the requirement for the 
format word beneath the saved PC, this trick no longer works - 
the stack can get out of sync and a format exception can be 
generated. So unless you are responding to an actual 
exception condition, don't play this RTE trick anymore! 


Along the same line, many programmers attempt to 
augment the instruction set of the 68000 by making use of the 
TRAP instruction. On receipt of the exception, they simply 
add 2 to the stack pointer to remove the saved status register, 
then proceed as though the routine were simply called by a 
JSR. This does not work any longer because the TRAP 
leaves a word or frame format information beneath the saved 
PC. MacWrite 4.5 is a particular offender here, as is 
MacFORTH. There may be others as well - we have all used 
this technique at one time or another - in the future, be sure to 
take account of the format of the frame, or don't use this 
technique. 
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By Our Readers 


Several popular programs (including the Mac ROMs) 
make explicit or implicit assumptions about the speed of 
execution of various code patterns, either for time delay loops 
or for SCC accessing which has internal setup delay 
requirements. The 68020 has an internal cache of 128 words 
and a pipelined architecture. Both of these, coupled with the 
varying overhead of memory accesses at different byte 
alignment boundaries, makes the timing of 68020 instructions 
impossible to predict, as well as being much faster than the 
older 68000 for the same clock frequency. 

This means that you should neither use instruction 
sequences nor loops to produce timing delays, especially if the 
delay has a critical lower bound as in SCC accessing! Even if 
the internal cache is disabled, you still have a pipelined 
architecture which overlaps instruction. execution, thereby 
increasing the speed of execution. The 68020 also completes 
each bus cycle in 3 clocks, instead of the 4 clocks which Was 
characteristic of the 68000. MacinTalk and many sound 
generation programs behave poorly here. 


In general, you should not assume that the exception 
vectors for the system are located in the page beginning at 
absolute address zero. They always were for a 68000, but the 
68020 allows them to be located anywhere since it maintains a 
vector base register internally. If you need to intercept an 
exception, you should first locate the vector page by reading 
the VBR with a MOVEC instruction. (But don't do this until 
you conform to the aforementioned exception protocol 
requirements.) Read below about current patches. 


Surviving with the Past 


Because of their daily importance to many of us, the older 
programs such as MacWrite 4.5 must be handled with care in a 
68020 environment. MacPaint and MacDraw appear to be 
OK. Here is the solution which we found to work for this one 
example program. Other programs such as MacFORTH may 
have different requirements. 

MacWrite 4.5 uses TRAP instructions to enhance its 
instruction set. In particular it uses TRAPs 0..4/6..9. In all 
except the case of TRAP 9, it assumes that it can simply 
remove the saved status register by incrementing the stack 
pointer by 2, then continuing as if called by a JSR. In the 
case of TRAP 9 it behaves properly by executing an RTE at 
the end of a very short instruction sequence. (The rationale for 
this one escapes us. Apparently they need a special 
instruction to increment a single register and force an 
alignment of some sort.) 
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The 68020 Solution 


Fortunately, the 68020 allows us to intercept these 
poorly handled TRAP calls by allowing us to generate another 
vector page. MacWrite alters the TRAP vectors in the 
original zero-based vector page. By creating a second vector 
page, and changing the internal VBR of the 68020, we get a 
first shot at all exceptions - including TRAPs. For the sake 
of MacWrite, our interception code for the TRAP 0..8 should 
adjust the stack frame produced by the exception so that it 
looks just like the ones generated by the 68000. Once this is 
done, we can permit MacWrite to continue by vectoring 
through its vectors in the page O table. (Fortunately, 
MacWrite does not alter the vector handling on the fly from 
one which ignores the exception to one which returns with an 
RTE, or vice versa). 

All other exception vectors in this new vector page 
should point to intercept code which in turn vectors through 
the vectors in the page 0 table. This allows any alterations to 
the I/O interrupt vectors to be accommodated without requiring 
the programs to know about our new table. 

The one vector which should be handled directly is the 
1010 exception vector used to access all ROM routines. 
Direct handling of this one seems safe since it never (?) 
changes and any additional vectoring indirection would cause 
undesirable runtime overhead. 

This solution works well for us. It is a tribute to the 
architecture of this superb chip that a solution is even 
possible. As far as we can tell, all other instructions are 
upward compatible with the older 68000. 

We do not yet have a solution for programs which 
generate sound such as MacinTalk and music synthesis 
programs. The voice and tones are very garbled and gravelly. 
We have found, however, that they sound better (but not 
correct) when the 68020 internal cache is disabled. 


Congratulations Apple 


Apple is to be commended for their efforts to look to the 
future. The 128K ROM code appears to be safe in all areas 
except for mouse SCC interrupt handling. It is remarkable 
that Apple did not shortcut the ROM code with respect to 
other exception types, expecially 1010, in light of the need to 
maximize performance. We look forward to a recoding of the 
ROM to take into account the bitfield instructions of the 
68020, effectively the inner guts of Bill Atkinson's Blitter in 
the chip. Graphics should really scream then. 

In the case of the SCC handling, the Apple ROM code 
made some implicit assumptions about the speed of execution 
of their ROM interrupt handler for the SCC. As it happens, 
this code executes on the hairy edge of being too fast on some 
Macintoshes, while on others, it is definitely too fast! 

Our solution was to install a new interrupt handler during 
boot time which assures that SCC accesses cannot happen 
closer in time than 2.2 usec. The way we did it was to force a 
RAM data memory access with a "MOVE.L (SP)(SP)" 
instruction placed at strategic spots in the interrupt handler. 
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The internal cache of the 68020 does not cache data, it only 
caches instructions. The RAM timing of the Macintosh 
assures that this will take at least about 2.2 usec. to execute 1 
read cycle/1 write cycle. 

The MC68020 with its 68881 math coprocessor are a 
welcome addition to the Macintosh. Initial benchmarks show 
that the internal instruction cache can make as much as a 2:1 
speed difference when switched on vs. when switched off. 
Even with it off, the 68020 is definitely faster than the 68000. 

We have run Smalltalk under the 68020 with quite 
favorable results, and it's quite pleasant to use now. We have 
yet to take full advantage of the 68881 math coprocessor. We 
expect a result several thousand-fold faster than SANE in 
software... P.S. You should see Life run with this chip! Our 
thanks to Jeff Brooks of Spectra Corp. for inviting us to 
participate in the testing of his 68020/68881 subsystem. 


SpaceExtra Needs 32-bit Fixed Argument 
James G. Haberly 
Mission Hills, CA 


In this note, James fixes an error in Inside Macintosh and 
reminds us of a useful ROM call for text manipulation. 


When attempting to produce fully justified text (both left 
and right margins), the "SpaceExtra" trap is a great help. Of 
considerably less help is the documentation. According to The 
Bible, "SpaceExtra" needs a 16-bit integer argument. It is 
quite obvious that this portion of The Bible was written by a 
heretic. "SpaceExtra" needs a 32-bit fixed argument (normally 
produced by "FixRatio"). 

How many compiler writers have assumed that The Bible 
was correct and moved a 16-bit argument to the stack? Check 
your favorite software package and see what it does. 
Fortunately, the error was not too difficult to find. Set 
TMON to stop the next time that "SpaceExtra" is used, look 
at the stack, step once, and then look at the stack. A 32-bit 
argument is now missing, not a 16-bitter. 

Final note on this bug for Mach2 users, (which is where 
I found it): if you do change the amount of extra spacing 
between words to print fully justified text, change the setting 
back to zero before you try to use Mach2's main window for 
normal input and output. The cursor does some very strange 
things otherwise. 


PostScript Banner Program 
James Haberly 
Mission Hills, CA 


In this pair of notes, James gives us some useful 
Postscript programs. Since our previously published Laser 
Print DA doesn't work on a Mac Plus, we will pay $100 to 
the first submission that re-writes it so it will work. There are 
two problems: first, the PAPSTATUS call now requires three 
parameters in the new ROMS, so a third parameter must be 
added. Second, the name of the currently selected LaserWriter 
is now contained in the file LaserWriter, not in the system 
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file, so an open resource must be done to fetch it. See Volume 
2, Number 2, Feb. for the complete source code. 


Imagewriter banner programs tend not to work with the 
LaserWriter. Here's a very simple PostScript program that 
will produce large banners (500-point fonts: one character per 
page). You need the Laser Print DA to be able to send the file 
to the LaserWriter, or use Bob Denny's PAP driver by 
including the Postcript in a simple Pascal or Basic program, 
or just use MacWrite with the Postscript Escape font from the 
June issue of MacTutor. The letters are outlined and filled 
with a light gray pattern because sending an all-black letter to 
the LaserWriter uses significantly more toner. Only one 
change, replacing "Text to be printed" with your message is 
required. [If using Postscript Escape, include gsave 
initgraphics at the front and grestore at the end to switch 
coordinate systems. Otherwise, text comes out upside down.] 
% Haberly: Laser:Banner 


% This file takes a string of characters and prints 
% them on a one-per-page basis using 500 point 
% Helvitica. The characters are outlines and filled. 


% How to use: 
% "Text to be printed." should be changed to 
% — Whatever you want turned into a banner. 


foanner { 
/strg exch def 
0 1 strg length 1 sub { 
150 200 moveto 
strg exch 1 getinterval 
false charpath 


S setgray gsave fill grestore 
Osetgray gsave stroke  grestore 
showpage 
) for 

) def 


/Helvetica findfont [500 0 0 600 0 0] makefont setfont 


% Change this next part to create a banner. 
(Text to be printed.) banner 


Anyone who has purchased the PostScript books from 
Adobe has seen the shaded headings that adorn each chapter. 
They look quite nice on report chapters, so here is a simple 
method of producing your own shaded headings. Replace 
(Text to be printed) with your own heading, and send to the 
LaserWriter using the Laser Print DA or use a Postscript 
Escape font in MacWrite. 


% Postscript Haberly 5/21/86 

% This file prints a chapter heading on a shaded background. 
% Replace "SIO Per Second" in the next line with 

% whatever you want to have printed. 


/boxMessage (Text to be printed) def 
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/boxLength 3 def 
fooxHeight 60 def 


/Helvetica-Bold findfont 30 scalefont setfont 


/nextBox ( 
boxLength 0 rlineto 
0 boxHeight rlineto 
boxLength neg 0 rlineto 
closepath) def 


Áintervals 150 def 


1 1 intervals { 
dup 1 sub boxLength mul 72 add 
8 72 mul 
moveto nextBox 
intervals div setgray 
fill 
) for 


96x coord 
%y coord 


“change shading 


intervals boxLength mul 72 add 


boxMessage stringwidth pop sub 5 sub — 96 x coord 

8 72 mul boxHeight 

boxMessage stringwidth exch pop 2 div 

sub 3 div add %y coord 
moveto %start ms here 
0 setgray 


boxMessage show 9eshow the header 


showpage 


Adapting MIDI and T'Scan devices to Mac Plus 
Ronald Spicer 
Surfside, CA 


Here is a handy source for the Mini-Din connector for 
those of you who want to wire your own Mac 512K to Mac 
Plus cable. (As with all hardware, use at your own risk. We 
haven't verified this material.) 

After buying a Mac Plus, a friend and I soon discovered 
that one of the common MIDI interfaces and the Thunderscan 
no longer worked. Through testing, the differences were 
discovered to be the lack of the +12VDC line, and that the 
*5VDC was moved to pin 6 on the adapter cables. To remedy 
this, an adapter must be made to include these two voltages. 
The following solution costs about $18 to build, as opposed 
to $50 to get your Mac Plus ‘converted’. Warning: do not 
connect these devices to a mac Plus unless the adapter is 
modified. 

Parts / Suppliers 

I ea. 8 pin MINI-DIN, pre-wired to 6 ft. of cable, $9.95 
from Advanced Computer Products, Irvine CA. 

l ea. DE-9B connector and shell, standard, from Radio 
Shack. 

l ea. power supply outputs at +5 and +12 volts DC 
approx. 200ma. each, $4.95 from Radio Shack, catalog #277- 
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1022. This is a Coleco power pack for their arcade game. 
The -5 volt line should be cut and taped off. 
1 ea. 8 conductor cable (choose your own length). 


Any further questions, contact Ron Spicer, PO Box 411, 
Surfside, CA 90743. 


INTERCONNECTION LIST 
(If using listed parts, then color codes match) 
8 pin mini-din DE-9B Power supply 


pins color  pinf color value 

1 leave open tape blue - - - 

2 orange 8 - - 

3 green 9 - - 

4 red 7 - - 

5 leave open tape black - - - 

6 brown 5 - - 

7 yelow 4 - - 

8 white 3 - - 

shell braid 1 &shell blue — ground 

n.c. n.c. 2 white +5vdc 

n.c. n.C. 6 red +12vdc 

- - - yelow -5vdc tape off 
(not used) 


Schematic of cable interconnect 


supply. 
(Coleco or 
Radio Shack) 


PIN6 IS +12VDC 
PIN 1 IS PS GRD 


From power ( PIN 2 IS +5VDC 


JUMPER SHELLS OF DE-9 AND 8PIN MINI-DINGO TO PIN #1 DE-9B 
LEAVE PINS 2 & 7 OPEN ON 8 PIN MINI-DIN 


Macintosh Fortran Compiler Bug List 
Pete Mahowald 
Stanford Electronics Laboratories 
Stanford, CA 


The following bug reports generally apply to version 2.1. 
Microsoft has now released version 2.2 and we would like to 
know how many of these have been fixed in the new version. 
Please report your findings to MacTutor so we can share them 
with our readers. 
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Summary of Bugs/Caveats/Suggestions 


1. Output from compiler program scrolls off screen. 

2. Display card at run time option means card numbers are 
included in the error message. Should be clarified. 

3. If 2.1 crashes during a compile, it leaves files which can be 
removed only by rebooting the computer. This is true of 
the 2.2 linker, librarian and compiled applications, but not 
the 2.2 compiler. All applications should be fixed. 

4. Control C during compile first stops the compiler (like the 
VAX) and then starts it (since control C is the keyboard 
equivalent for compiled). This is unexpected. 

5. Run time errors give the line numbers with respect to the 
first line of the subroutine, but they do not say which 
subroutine they occur in. Need better identification. 

6. Include is sensitive to trailing blanks. Shouldn't be. 

7. Printer and modem ports are inaccessible. Should be! 

8. Include statements cannot be nested. 

9. Control S and Control Q don't always work during program 
execution. Control decimal won't always stop program 
execution. 

10. Error messages from the compiler during run time can be 
invisible if the cursor was left on the bottom or right hand 
side of the screen. 

11. The Macintosh disks are not 
utterly dependable, and 
occasionally bugs creep into 
the compiler, run time library 
and operating system. Keep 
a backup, and if it does 
strange things, copy the 
backup onto the working 
disk. 

12. Stop statement with a 
message following will not 
be seen since it will exit 
directly to the finder. End 
statement should pause. 

13. Cannot allocate the heap 
based on machine size. Very 
little information is given 
about how big the heap 
should be. It should be equal 
or greater than the local 
storage plus code of any 
loaded subroutine, however 
this information is not readily available. Program won't run 
on huge Mac due to heap space, yet this is not obvious. 
Appears broken. 

14. Array checking doesn't always check the lower bounds. 

15. Dynamically loaded routines must be self contained, and 
cannot reference routines in the root section. 

16. The error message reporting subroutine which is an option 
in the Program statement cannot process all of the various 
types of errors! A frustrating example of poor quality. 

17. Dynamically loaded routines will be reloaded each time 
they are used, unless they are recursive, even if they were 
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just loaded. 

18. Compiling a program with a missing format statement 
label will cause the compiler to crash if the operating 
system is HFS. 

19. The debugger will not restore the cursor when it regains 
control from the user program. Thus if your program calls 
HIDECURSOR, you cannot use the cursor in the debugger. 

20. Under MFS, it will not put the symbol, list and 
applications files in the same folder where the source came 
from. 

21. Unit 9 does not respond to Fortran Carriage control. The 
first character is not trimmed off and used to get a new page, 
double spaced line, or typing on the same line. 

22. There is no cursor for data entry. 

23. Control S. and Control Q have opposite meanings under 
the debugger and while the program is executing. 

24. Debugger crashes a lot. 

25. In the debugger, holding down the scroll arrows (distinct 
from clicking them occasionally) causes the program listing 
window to scroll incorrectly. It moves the cursor but 
forgets to move the text until the arrow is released. 

26. Function names aren't in the symbol table and the 
debugger cannot display values returned by functions. 

27. In the debugger, in the variable command, entering a 
different array element than one already in the list doesn't do 
anything. 

28. Printing from the compiler cannot be stopped by a control 
decimal. 

29. Neither the compiler nor any programs can use the 
LaserWriter! This is a glaring omission. 


30. The compiler diagnostic "unterminated DO loop in 
program unit" doesn't include the name of the program 
which generated the error. 

31. In the linker, capital letters do not always work correctly. 

32. First file-not-found is fatal for the linker. (Either script 
file or object files). 

33. Can have only one entry point per file in the linker. 

34. F77.RL must be specified in small letters. 

35. Incorrectly states the number of unresolved external 
references. It actually reports the number of resolved 
external references. 

36. Debugger doesn't always know the maximum size of 
arrays. 

37. End of record and end of file when using unformatted 
sequential files are ignored. 

38. Script files for the compiler and the linker are quite 
different in format. 

39. Compiler isn't shipped with HFS system, nor with the 
best choice of MFS systems. 

40. Linker should have a transfer command where it executes 
the file it just linked. 

41. Fortran maps don't have array sizes and dimensions. 

42. If Errmsg.sub is linked, the linked copy is not used. 

43. Bug box for list compile obscures error messages. 

44. List compile cannot be stopped once in progress. 

45. No error message if f77.rl is not linked and not found. 
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Visual Programming 
A Text Editor in VIP 


r 


V.I.P. - The Next Generation 


Readers of this journal will 
agree there is no dearth of 
programming languages for the 
Macintosh: more than a dozen by 
rough count. What these languages 
generally have in common is their 
genesis - they all came into being 
before the Macintosh. So with the 
arrival of the Mac, a number of very 
clever people devised schemes to 
extend these languages. Key words, 
words, trap macros, and functions 
with 'glue' were created expressly for 
the purpose of accessing Mac's 
ROM. This was a remarkable 
achievement, but not one without a 
price. 

To create the illusion of simplicity demanded of 
Macintosh applications, programmers not only had to read, 
understand and interpolate the wisdom of "Inside Macintosh", 
they also had to reorient their thinking about how programs 
should operate. (Remember "Everything you know is 
wrong"? Obviously some people were able to overcome these 
obstacles). 

But what about the rest of us? Those of us who have 
attempted to unlock the treasures of the ToolBox, only to 
discover that programming on a Mac is not as simple as using 
one. That rest of us who just want to create Macintosh 
programs quickly and easily for our own purposes and 
amusement. 

Programming should be fun. [Tell that to the makers of 
MPW. -Ed] Programming IS fun. There's nothing quite like 
the thrill of accomplishment when a programmer's creation 
finally does what it was designed to do. However, I suspect 
many would-be programmers never realize the programmer 
‘high’, and become frustrated at the prospect of deciphering 


Inside Macintosh and typing thousands of lines of source code. 


If you haven't yet been able to crack the ToolBox barrier, 
and typing is not high on your list of fun things to do, let me 
introduce you to a totally new concept in Macintosh 
programming. 


Point and Click Programming 


Visual Interactive Programming (V.LP.), written by 
Dominique Lienart and published by Mainstay, is a Macintosh 
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approach to Macintosh programming. ^ V.LP.s unique 
programming environment is shown in Figure 1. Displayed 
in V.LP.s Editor window is a portion of a Routine. A 
routine is simply a logical grouping of V.I.P. Logic forms 
and Procedures. Each routine has a name and all V.I.P. 
programs start in main. 

Logic forms in V.I.P. vernacular are the classical looping 
or branching constructs, e.g., For i to n, While-repeat, if-then- 
else, switch, and a programmer-defined routine call are 
provided. Logic forms are entered into routines by clicking on 
one of the icons in the middle group to the left of V.I.P.'s 
Editor window. The icon in the middle of the top row has a 
special purpose. Clicking on this icon provides a global view 
of an entire routine (Figure 2). The dotted rectangle repre- 
sents the visible area in the normal screen mode. By dragging 
this rectangle, the programmer may quickly move to any por- 
tion of a routine. Clicking on the eyeball icon again returns 
to the normal screen view, at the position selected. "Very 
handy to quickly move several screens when a routine is large. 

V.I.P. as you can see, is a structured programming 
language. In fact its impossible to 'write' a V.I.P. program 
that isn't. The graphic display in flow diagram-like form is 
automatically drawn and adjusted as necessary to maintain 
program structural coherence as procedures or Logic forms are 
added, deleted, or moved during program development. 

Procedures are the work horses of V.I.P.. The lower 
group of 15 icons are the Procedure classes. Clicking on a 
Procedure class icon opens a dialog displaying a list of the 
Procedures for that class, as in Figure 3. The selected 
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Figure 2 


Procedure is immediately displayed in V.I.P.'s Editor window 
at the position indicated by the Insertion Arrow. Figure 4 
shows a Procedure called, appropriately enough, "new 
window". The Procedure is enclosed in a Frame and 
automatically displays its input window with the first field 
requiring programmer input highlighted. Each input field is 
identified, and the input or output argument's type is shown in 
parentheses. In this example, the programmer enters 
arguments in 7 fields. A field may contain up to 245 
characters, and is scrollable by clicking on the arrows on either 
side of the input field. An optional Comment field is also 
provided. Clicking the down arrow to the right of the 
Procedure's name opens or closes the input window depending 
on its previous state. 

Clicking the small rectangle to the left of the Procedure 
name selects the Procedure for editing. A single Procedure or 
even an entire routine may be cut, copied, pasted, or cleared in 
Standard Macintosh fashion. An Undo command is also 
provided in the Edit menu. Editing of individual fields is also 
accomplished in standard Macintosh fashion. When in a text 
edit field, the cursor changes to the familiar I-beam. Text may 
be inserted, selected and cleared by backspacing, or Cut, 
Copied, and Pasted using the standard clipboard. 

V.I.P. provides more than 170 precompiled Procedures to 
greatly simplify programming of windows, menus, dialogs, 
alerts, events, text editing, character Strings, graphics 
(including regions), integer and floating point arithmetic, 
Sounds, and more. Regardless of the complexity of a 
Procedure's underlying code, all Procedures interact with the 
programmer in the same way. Different Procedures, of course, 
require different arguments or expressions. However, the 
programmer is never left guessing as to what they should be. 
Input is checked as soon as possible, and the programmer is 
notified of invalid input with a plain English alert. 

V.I.P. works on "Objects" which may be of type byte, 
integer, real, point, or rectangle. Symbols, or names, if you 
prefer, are assigned to objects by clicking on an object in the 
top group of icons, and entering the desired symbols for that 
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type, as in Figure 5. Similarly, arrays are 
dimensioned, and all objects must be declared 
before a program will run. If an object has 
not been declared or is improperly defined, the 
programmer is alerted and the Procedure is 
automatically selected with the suspect field 
highlighted. Objects may be declared to be 
global, that is, recognized by all Routines of 
a program, or be local only to the Routine in 
which they are declared. Globals can be 
initialized and bound to an initial value which 
will be assigned to the corresponding object 
just before execution. Symbolic constants 
may also be defined by the programmer, and 
are global in nature. By selecting the 'Define 
Arguments...’ command from the Routines 
menu, the programmer may define 
arguments for a Routine using an editing 
dialog, as in Figure 6. The order of the 


arguments is defined by the programmer, and is important to 
assure that argument passing between the caller and called 
Routine is done correctly. Arguments can be considered to 
belong to the automatic class of objects, as opposed to objects 
represented by global symbols, which are static. 

V.LP. also provides an integrated Debug mode where you 
can trace program flow, monitor entry and exit to routines, 
examine and set object values, and observe selected variables 
during program execution. (See Figure 7). A graphic view 
of the relationship of all routines in a program is obtained by 
selecting 'Show Relations' from the Routines menu. (See 
Figure 8). Entire Routines may be copied to Deskscrap and 
pasted into MacDraw or other programs capable of handling 
object oriented graphics. In this fashion, a graphic 
representation exactly as it appears in V.I.P.'s Editor window 
can be modified if desired and printed - great as an educational 
aid. V.I.P. also offers the choice of saving a program in three 
special formats. The default choice is V.LP. proprietary 
format, which may be run by clicking on its icon, or opened 
subsequently and edited as necessary. The second option is 
RunVIP', which allows files saved in this format to be 
executed directly by the Run time module, which is included. 


new window 
kill window 
clear window 
set window title 
set window port 


set text font 
set text size 
set text face 
get font info 
activate window 


Figure 3 
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The third choice is "Text. V.I.P. created Text files may be 
opened by any text editor, and is useful for publication of 
program listings. 

V.I.P. also allows Routines to be renamed if desired and 
saved in separate files which can be merged with any other 
program. A programmer can also Search for any text string 
within a program and change any programmer entered 
expressions or arguments. By selecting 'Show Stats...’ from 
the Special menu a window showing the size in bytes of the 
program, global and local objects, and free memory is 
displayed. (See Figure 9). Tie all of this together with 
good documentation which includes a tutorial and reference 
section, and you're able to create a program 10 minutes after 
you open the package. 

If all of the features described so far haven't convinced 
you that V.I.P. is in a class by itself, and head and shoulders 
above the rest, read on; the best is yet to come. 
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Closing The Loop 


Remember earlier when I was talking about languages 
being extended? Well, now let me put that, and hence the 
advantage of V.I.P., in perspective. If you look at source code 
for programs implementing the Macintosh standard user 
interface, you will find the amount of code necessary to evoke 
the magic of Mac's ROM usually far exceeds the rest. To give 
you an idea what I'm getting at, let's compare the amount of 
code a programmer must write to create a relatively simple 
Text Editor. In his excellent book "Macintosh Revealed, 
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Figure 6 
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VoLII, Programming with the ToolBox", Stephen Chernicoff 
presents Pascal source code for MiniEdit - about 2000 lines. 
On the MacPascal disk is another example of an Editor which 
requires 447 lines of code. 

V.I.P. code to create an Editor with more features than 
MacPascals example takes only 50 lines (see listing), but 
that's not even the best part. The listing as shown is produced 
by selecting "Print... from the File menu. V.I.P. does the 
indenting and prints the names of all Logic forms and 
Procedures in italics. Programmer entered arguments and 
expressions are shown contained within parentheses. 


@© Global © Local 
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Figure 5 


Including Symbols, only about 300 keystrokes and a few 
dozen mouse clicks were required to create a reasonably 
functional Text Editor. It is certainly easier to create V.I.P. 
code than to write words for this column. 
V.I.P. is an interpreter, and as such is ideally suited for 
beginners, or programmers with skills in other high level 
languages seeking a painless introduction to the Macintosh. 
V.LP. can also form the nucleus of an extremely powerful 
and versatile development system. With Translator modules, 
which will be sold separately, entire V.I.P. programs can be 
automatically converted to 'C' or Pascal source code, ready for 
compilation with your favorite system. Mainstay plans to 
release Translators for Lightspeed C and Pascal, MegaMax and 
Aztec C, TML Pascal, and others. Imagine the benefits of 
developing and debugging in a friendly, interactive 


environment, and with a few additional 
mouse clicks, having a ready-to-run, 
standalone application. 

V I.P. does not require memorization 
of key words or typing of arcane syntax. 
There are no BEGIN's, END's, or curly 
braces to keep track of, no FOR's without 
NEXT's, or IFs without ELSE's. If you 
are already proficient in another 
programming language, you will find 
V.I.P. not contrary to usual conventions. 


(€) output 


insert 


Source Code Short Course 


A printed copy of a V.I.P. program's 
source code is obtained by selecting 
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"Print..." from the File menu. What is printed is not source 
code in the usual sense, it is actually an output of a V.LP. 
program. 

Each listing includes the program's name, day of the 
week and date at the top of each page, and page numbers at the 
bottom of each page. The first page always lists the symbols 
for each Object type declared in the program. Dimensions of 
arrays are printed within brackets. The program listing always 
begins on page 2 with the main routine. Other routines 
defined by name are printed in alphabetical order on separate 
pages. V.I.P. defined names for Procedures or Logic forms are 
printed in italics. Programmer-entered arguments or 
expressions follow the Procedure or Structure name, and are 
printed within parentheses separated by commas. The order of 
these arguments or expressions corresponds to the entry order 
defined by the respective procedure. 

Creating a V.I.P. program by following a printed listing 
is a simple task. Open V.I.P. by double-clicking on its icon 
and select New from the File menu. Select the first Procedure 
in the listing by clicking the appropriate Procedure class icon 
and select the Procedure name as printed in italics. Enter the 
arguments as printed within the parenthesis in the Procedure's 
input window fields. Repeat the process until all procedures 
and Logic forms in the listing are completed. Define objects 
by clicking on each Objects type, and entering the symbols as 
listed. Save the program with a name you choose. That's all 
there is to it. 


DrawSection | 
JU 0 a 
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All V.LP. programs start in main, and as our example 
program has but a single routine, it is named main by default. 
The first four procedures take care of defining the menus and 
menu items. Arguments to the new menu procedures are the 
menu's title, which is a text string enclosed in quotation 
marks, and the menu identifiers, i.e. mn[1] and mn[2]. In this 
example mn[ ] has been declared a single dimension array 
with two elements of type ‘byte’. Each menu is provided with 
its menu item list by the append menu item procedures. The 
entire menu item list is a text string enclosed in quotes. Items 
are separated by semicolons, and their order determines their 
relative position in the menu. An open paren "(" disables the 
menu item, and a "(-" puts a non-selectable dotted line 
between groups of related menu items. A "/" preceding a 
character designates a keyboard equivalent command. 

The next two set rect procedures define the top, left, 
bottom, right coordinates of the program's window and port 
respectively. These coordinates are identified by the symbols 
T, and 'rl', which are of type rectangle. Why two set rect 
procedures? Let's take a look at the next procedure in the 
listing, and I'll try to explain. The procedure new window as 
shown in figure 4 requires 7 arguments. For our Text Editor 
we have specified window type 1, which is a standard 
document window with a size box and scrollbars. Any value 
which is + O entered in the ‘text only' field indicates the 
window is intended for text only. Autorefresh is set to 0, 
however in the case of text only windows, any necessary 
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Figure 8 


updating will be handled automatically. The fields window 
rect and port rect now receive the symbols 'r' and 'r1' which 
represent the TLBR values assigned previously in the set rect 
procedures. 

A window drawn on the screen, or even the entire 
Macintosh screen itself provides only a limited view of a 
graphics port. Imagine a big graphics port which you can 
slide around under a window to view various portions. For the 
graphics port belonging to our Text Editor window, we have 
set the top left corner of the port rectangle to 0,0. Now any 
drawing in the graphic port will show up where we expect it 
to, even if we resize or move the window. 

Also note we have set the bottom coordinate of the port 
rect to a value greater than the height of the window to enable 
the vertical scrollbar whenever the contents of the window 
exceed its vertical dimension. The right coordinate of the port 
rect however, is set to equal the window width, thus 
effectively establishing the line length. To conclude the 
arguments to the new window procedure, the window title, 
"Text Editor" follows, and finally the symbol 'w' referring to 
the window itself. 

When the program is run, the menu bar is drawn, the 
Text Editor window is displayed, and a standard file dialog is 
presented as called by the procedure get document name. The 
first argument, if TRUE i.e., 40 launches the "Save..." dialog, 
else brings up the "Open..." dialog. If desired, a prompt string 
may be entered, e.g. "Save file as: ", but in this case we don't 
need any, so a set of double quotes serve as a field entry. The 
next field is 'type', and because we want to see text files only, 
we specify (TEXT. A non-zero value is returned if the 
procedure is successful and the user, in this case, selected a file 
and clicked the Open button. The symbol 'load' will receive 
the returned value, and also when the result is #0 the 
documents name is returned to the symbol 'doc'. The program 
now checks if (load) is true, and if so, activates the procedures 
open file,load text, and close file. Else do nothing. 
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The heart of nearly every Macintosh program is a loop 
containing a 'get next event' sequence of instructions, and our 
example program is no exception. While t # 4, explicitly 
means while the user has not clicked in the window close box; 
get next event. V.I.P.'s get next event procedure is a model of 
elegant simplicity. By providing just 4 arguments: type, 
point, message, and ID (defined here as t, p, m, and i) we 
have the necessary objects in place to monitor events. All 
that remains is to specify the actions to be taken when an 
event occurs. 

Two if's and a switch structure direct the program flow to 
handle specific events. The first if checks for an event type 
equal to 1, which is a menu command. The next if is executed 
when a menu command was returned, i.e., t-1, and tests 
whether the message returned in m is equal to mn[1], and if 
so, invokes the switch structure. The cases of the switch 
structure are selected by the menu item returned in i. The 
procedures cut text, copy text, paste text, and clear text require 
no arguments. Justify text and space text take as their 
arguments the value of 'j' and 's' respectively, providing 
centered justification and double-spacing in our example. 

Finally, when t=4, i.e., the mouse has been clicked in the 
window's close box, another get document name procedure is 
executed. This time a "Save..." dialog is presented with the 
prompt string "Save text as :". The final if structure 
expression is evaluated and if save is TRUE (user clicked the 
save button), the procedures open file, save text, set 
end of file, and close file are executed, saving all text in 
window 'w' with the name returned by 'doc. The exit 
procedure clears all objects from memory and returns us to 
V.LP.s Editor window. Figure 10 shows "Text Editor" in 
action, and concludes our short course. 

If I had to describe V.I.P. in 10 words or less, my best 
shot would be; "A single V.I.P. procedure may be worth a 
thousand words." V.I.P. is truly a unique programming 
environment. Try it, I know you'll like it. 


O The Complete MacTutor, Vol. 2 


ext Editor 


|] the relationship of all routines in a program is obtain OE 
| | ‘Show Relations’ from the Routines menu. Figure 8. Ei EE. 
| | may be copied to Deskscrap and pasted into MacDraw t 
d capable of handling object oriented graphics. In this 1 


- representation exactly as it appears in V.I.P.'s Editor: 
|| modified if desired and printed. Great as an education 
|] offers the choice of saving a program in three special 


Figure 10 


Text Editor - Visual Interactive Programming (V.I.P.) 


byte 
doc[60] 


new menu ("Edit",mn[1]) 
append menu item (mn[1],"(Undo;(- 
;Cut/X;Copy/C;Paste/V;Clear;(-;Justify; Space") 
new menu ("Print",mn[2]) 
append menu item (mn[2],"Page Setup...;Print...") 
set rect (50, 12,330,500,r) 
Set rect (0,0,1000,488,r1) 
new window (1,1,0,r,r1,"Text Editor",w) 
get document name (0,"","TEXT",load,doc) 
if (load) 
open file (doc,1,"????" f) 
load text (f,w) 
close file (f) 
else 


while (t « 4) 


get next event (t,p,m,i) 
if (t = 1) 
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In future columns 
well take a beginner's 
course in Visual [nteractive 
Programming. Our ap- 
proach will be somewhat 
different from traditional 
methods for a couple of 
reasons. First, V.I.P. pro- 
gramming is not tradi- 
tional: it's easy. Secondly, 
since most Macintosh pro- 
grams have menus, win- 
dows, dialogs and events, 
thats where we'll start. 

In the meantime, if 
you have questions about 
VIP. I check in on 
Compuserve, [71645,1543] 
and Delphi or GEnie, user 
name BLUCKIE. Happy 
V.I.P. 


switch (i,1,2,3,4,5,6,7,8) 


case 1 
case 2 


case 3 

cut text 
case 4 

copy text 
case § 

paste text 
case 6 

clear text 
case 7 


case 8 
assign (1 - j,j) 
justify text (j) 
case 9 


assign (1 - s,s) 


space text (s) 
else 
if (i = 1) 
set up page 
else 
print text (w) 
else 


get document name (1,"Save text as :","",save,doc) 
if (save) 


else 


exit 


open file (doc,2,"????" f) 
save text (f,w) 

set end of file (f) 

close file (f) 


Assembly Language Lab Q 


"Wired for Sound" 


Can You Keep a Secret? 


One of the Macintosh's best kept secrets is its wonderful 
Sound driver. This beauty is capable of generating a variety of 
sounds including simple tones, multi-voice music, complex 
speech, and digitally recorded sounds. In spite of its power, 
it is relatively easy to use once the programmer takes the time 
to understand a few basic concepts. This month's column 
concerns itself with the sound driver and the techniques the 
programmer must employ to use it First will come a 
description of the device manager, with emphasis on it's 
relation to the sound driver in particular. The actual sound 
driver description is next, followed by a sample program that 
ties it all together. 


First Things First 

First, a bit of background information on the device 
manager. The device manager is the part of the Macintosh 
ROM that allows the use and control of devices, which are 
usually hardware peripherals connected to the Mac. Examples 
of devices are the serial ports, the disk drives, the sound 
driver, etc (desk accessories are also considered devices, 
however, we will not include them in our general discussion). 
There are two types of devices: character and block. 
Character devices can read or write only one character at a time 
and they must do so sequentially. That is, they cannot access 
any data other than the very next character. Whereas block 
devices read and write data in 512 character blocks and are 
randomly accessible. This means that they have access to any 
block of data, regardless of its position. Another matter of 
note is that many device manager routines may be executed 
either synchronously or asynchronously. Synchronous 
execution means that the calling program remains idle while 
the requested I/O operation is performed. Conversely, 
asynchronous I/O operations are performed while the calling 

program is running. 


Now Some Specifics 

The device manager is one of the portions of the 
Macintosh ROM that has a register based calling interface. As 
you may remember from previous columns, this means that 
the programmer invokes the desired trap macro with address 
register AO pointing to a data structure in memory. It is 
through this data structure that parameters are passed between 
the calling program and the routine. 


The data structure that the device manager 
routines use is called the joParamBlock (from here on 
abbreviated as ioPB). Figure 1 shows the structure of the ioPB. 
The numbers in parenthesis 


are the byte offsets from the base address of the ioPB. There 
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is a byte-division ruler to the right of the figure to ease the 
judgement of lengths. 

The programmer need not concern himself with the first 
four fields of the ioPB, the device manager routines use them 
internally. 

The fifth field, ioCompletion, is used for asyncronous 
I/O operations. When the device manager has finished an 
asyncronous operation, it will jump to the routine pointed to 
by ioCompletion, if it is nonzero. For example, you could 
request that the device manager send a page of data 
asynchronously through the serial port. While the device 
manager was doing this, you could set up the next page of 
data to be sent. When finished, the device manager would 


jump to your completion routine, which in turn would send 
the next page of data. 


Upon returning from a device manager call, the ioResult 
field will contain a code describing what error, if any, 
occurred. IoNamePtr is only used when first opening a device. 
It points to the name of the device to be opened. All open 
devices are assigned reference numbers by the device manager. 
These reference numbers must be specified by the calling 
program and are stored in the ioRefNum field. 

The device driver allows Control/Status calls to certain 
devices. These calls allow the user to send commands to 
devices (such as configuration commands) or to get status 
information from devices. A control/status call requires that 
the programmer send a control code to the device; this code is 
contained in the CSCode field of the ioPB. Certain control 
calls also need parameters of their own. These parameters are 
passed through the CSParam field. 

When a read or write call is made, the address of the data 
buffer is passed in ioBuffer. The number of bytes that the 
programmer wants to read or write is contained in the 
joReqCount; the number of bytes successfully read or written 
is returned in ioActCount. IoPosMode and ioPosOffset are 
used only with block devices. They allow the data to be 
accessed non-sequentially. 

To use the sound driver from assembly language, the 
programmer must set up the appropriate fields of the ioPB, 
load AO with a pointer to it, and then call the trap macro. 
Asyncronous execution is flagged by appending ",ASYNC" to 
the end of the trap name. For example to write a data buffer to 
a device, you would set up it's reference # etc. in the ioPB, 
store a pointer to the buffer in the ioBuffer field, load AO, 
and then execute Write,ASYNC. 


The sound driver is broken into three pieces: the square- 
wave X synthesizer, the — four-tone synthesizer, 
and the free-form synthesizer. Each synthesizer generates a 
different type of sound and requires a specific amount of 
processor time. Each type of sound is generated by making a 
write call to the device manager requesting that the proper data 
is sent to the sound driver. The square-wave and four-tone 
synthesizers will be described here. 


Nothing Fancy 
The simplest subset of the sound driver is the square- 
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wave synthesizer. When running asynchronously, the square- 
wave synthesizer uses approximately 2% of the processor's 
time- a modest degree of overhead. However, the type of 
sounds that this synthesizer is capable of creating are limited 
to simple tones or beeps. 

To get the square-wave synthesizer going, the 
programmer simply writes a SWSythRezc to the sound driver. 
The first word of the SWSythRec is -1. This tells the sound 
driver that the data in the record should be routed to the square- 
wave synthesizer. Following this is a list of tones to be 
produced. The end of the tone list is dentoed by a zero. 

Each tone is 3 words long. The first word is the count 
value, where frequency = 783360 / count. Complete lists of 
count values for the C major scale and the equal tempered scale 
are contained in Inside Macintosh. The second word is the 
amplitude, or volume, of the tone. This value ranges from 0- 
255 inclusive, with 255 being maximum volume. The last 
word is the duration of the tone, in 1/60tPS of a second. 

An example set of data will make the above explanation 
clearer. The sample will be 3 tones with frequencies of 1000, 
2000, and 4000 Hertz. The amplitude of the tones will be 
half volume. The lengths of the tones will be .5, 1, and 1.5 
seconds. 

The count values are calculated by dividing 783360 by 
the frequency. 783360/1000 = 783; 783360/2000 = 392; and 
783360/4000 = 196. The amplitude will be 127 ( half of 255 
). Given that 1 second = 60 duration units, calculating the 
duration values is done by: (.5 )* 60 = 30; 1* 602 60; 1.5 
* 60 = 90. 


A Barbershop Quartet in Your Mac 

The four-tone synthesizer is the most taxing in terms of 
processor use- approximately 50%. However, it allows up to 
4 tones to be produced simultaneously, allowing multi-voice 
music and chords to be produced. Its record, FISynthRec, 
has the most complex structure of the three synthesizers. 

The first word of data in the FTSynthRec is always a 1. 
Following this is the duration of the sound, again in 1/60ths 
of a second. Next are 4 pairs of values for each of the four 
tones to be produced. 

The first long word of each pair is the rate value, a fixed- 
point number which is analogous to the SWSynthRec's count 
value. (A discussion of fixed-point numbers can be found on 
page 11 of the Memory Manager Introduction in Inside 
Macintosh ) In this case, the frequency is derived by the 
formula: frequency (Hz) = 1000000 / (11502.08 / rate). The 
last element of the pair is a long integer phase value. The 
phase can range in value from 0-255, and tells the square- 
wave synthesizer how many bytes in the tone's waveshape 
definition to skip before starting the tone (If this confuses 
you, don't worry about it. Great sounds can be created 
without any regard for phase). 

After the four pairs of values come four Waveshape 
pointers, which point to waveshape definitions in memory. 
Each waveshape definition consists of 255 bytes that describe 
the shape of one pulse, or click, sent to the speaker. 
Consider a tone of any frequency. It is comprised of a series 
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of pulses, or "clicks", that create a tone when generated at a 
certain rate. The pulse itself is a general unit used by all 
tones, and therefore has no effect on the frequency of the 
resulting tone if it is designed correctly. Figure 3 shows the 
waveform description of a square pulse. Although it is the 
simplest possible waveform to generate, it is not as "natural" 
sounding as a sine pulse. In most cases, a square pulse or a 
sine pulse will suffice; however, by changing the wave 
definition, various musical instruments can be simulated. 


The data looks like this: 


Tone #3 


O o 


A C major chord will suit well for a set of sample data. 
This chord is comprised of the notes C, E, and G. The table 
in Inside Macintosh gives us fixed-point rate values of 
3.03654, 3.79568, and 4.55481 for these notes. The 
equivalent hex values for these numbers are $030959, 
$03CBBO, and $048E06 respectively. A duration value of 60 
will generate the sound for 1 second. Using the default phase 
value of 0, the only remaining task is the initialization of the 
waveshape definitions and pointers. 

The sample waveshape definition is created by filling a 
255 byte block of memory with data - the first half (bytes 0- 
127) with the value 255 and the last half (bytes 128-255) with 
the value 0. When this is done, the address of the block of 
memory is stored in the waveshape pointers of our three tones. 

There are two other differences that make the four-tone 
synthesizer different from the square-wave synthesizer. After 
the FTSynthRec is set up in memory, it is not directly 
written to the sound driver. Rather, a six byte block is 
written. The first two bytes comprise an integer word of value 
1. The last four bytes of this block contain a pointer to the 
actual FTSynthRec in memory. The second difference is that, 
by nature of this calling scheme, only one FTSynthRec can 
be written at a time. Therefore, it is necessary to loop if 
there is more than one sound to generate. 

The program gives examples of using both the square- 
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wave synthesizer and the four-tone synthesizer. One useful 
item is the macro named Center, which when given a string, 
the center X coordinate of the grafport, and the Y coordinate at 
which the text should appear, will draw the text centered at 
the given Y coordinate. This saves a great deal of "hit-and- 
miss" experimentation if, like me, you don't sit down and 


255 


Square wave pulse 


calculate the correct centers by hand. 

With this information and a bit of patience, the average 
reader should be able to implement sound in his next assembly 
application to give it that special touch of style. 


,9999999999990990090099009009090900 


;** Sound Example #1 ee 


,99999999999999999099909009000 

€ 1985 By Chris Yerga for MacTutor 
INCLUDE MacTraps .D 

; Declare external labels 

XDEF START 

; Define Macros 

; Note that this clever macro will center a 
; String for you about the MidPT, on line Y 
; for use with the .DrewString trap call. 
MACRO Center 


CLR.W -CSP) 


String,MidPT,Y = 


Save room for INTEGER 
width of string 
PEA — '(String)' 
-StringWidth 
CLR.L D3 ;Clear the high word of 
;D3 so the DIVU works 
;Get the width Cin pixels) in D3 
;Divide by 2 


MOVE .WCSP)+,D3 
DIVU 52,03 
MOVE .L #8 (MidPT),D4 
SUB.W D3,D4 ;Subtract (Width/2) 
;from center point 
MOVE.WD4,-(SP)  ;Push the X cordinat 
MOVE .Wt (Y), -CSP2;Push the Y cordinat 
-MoveTo Position the pen 
PEA — '(String)' 
-DrewString 
| jEnd of Macro symbol 


;*** Local Constants *** 


AllEvents EQU —$0000FFFF 
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Here is a sample FTSynthRec with the data for a C major 


chord: 


$030959 


$03CBBO 
$048E06 


Count 


Phase 


Count 


Phase 


Count 


Phase 


Count 


Phase 


MaxEvents EQU 12 


DWindLen EQU $AA ; see DS storage area 


; Start of Main Program 


BadPtr: Debugger Should never get 
;here. Is called when there is 


Duration 


WaveSh 


oe Def 


,8 problem with the memory 


;manager. 


START: MOVEM.L D0-D7/A2-A6, -CSP) 


LEA — SAVEREGS, Ad 
MOVE.LA6, CAO) 
MOVE.LAT7,4CA0) 

; Initialize the ROM routines 


PEA -4(A5) 
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;,QD Global ptr 
-InitGraf jInit QD global 


-InitFonts ;Init font manager 


-InitWindows ;Init Window Mgr 
-InitMenus ;Guess what...yes! 
CLR.L -CSP) 

-InitDialogs 

-TEInit ;Init ROM Text edit 

MOVE.L f*AllEvents,DO 

-FlushEvents 

-InitCursor ;Get the standard arrow 


jAllocate the memory that we need 


MOVE.L 5550,D0 ;Get a 50 Byte 


;nonrelocatable block 


-NewPtr 
CMP *0,D0 ;Did we get the block?? 
BNE — BadPtr ;Nope...jump to MacsBug 


LEA ParamBlock,A1 ;Save the Ptr 
MOVE.L A@,CA1) 
MOVE.L #255,DØ 


;Get a 255 byte block for waveform def 


-NewP tr, CLEAR jand fill it with 

,zeros while you're at it 
CMP #9 DO ;Did we get the mem? 
BNE BadPtr ,Nope...Debugger time 


LEA Wave,A1 
MOVE.L A2,CADD 
; Set up the ioParemBlock fields 


;Save the Ptr 


MOVE.L ParamBlock, AQ 


CLR.L  12CA0) ¿No completion routine 

MOVE.W 3-4,24CA0) ;The Sound Driver reference * CLR.W 
44CA0) ;Standard positioning 

CLR.L — 46CA0) ,No offset for the write 


;Get the Ptr to ioParamBlock 


;Fill the Wave buffer with a simple ;Square Wave definition 


MOVE.L Wave, Ag ;Get the base 
address of the block 
MOVE.L 5127,00 ;Set up the wave definition 
MakeWave : 
MOVE.B #255, CA@)+ ;Set bytes 0-127 of the wave def 
jand increment Ag 
DBRA D@,MakeWave j loop until 127... 
;Set up the Dialog Box 


CLR.L -CSP) ;Save room for DIalogPtr 
MOVE.W 8128,-CSP) ;The ResID of the dialog 
PEA DStorageCA5) ;Where to put the DialogRec 
MOVE.L $-1,-CSP) ;Put it in front, 
-GetNewDialog 
LEA DHandle, A2 ;Save handle, but keep it 
MOVE.L (SP5,CA2) jon the stack 
-DrawDialog ;Draw the dialog.. 
LEA DHandle, A2 
MOVE.L (A2),-CSP) ;Set the Dialog to 

; the current GrafPort 


-SetPort 

MOVE.W #7,-CSP) ;Select Athens 
-TextFont 

MOVE.W #18,-CSP) jin 18Pt size 
-TextSize 

Center Sound Example #1,206,35 
MOVE.W #1,-CSP) ;Select Chicago 
-TextFont 
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MOVE.W #12,-CSP) 
-TextSize 


Center 


jin 12Pt size 


61985 Chris Yerga for 
MacTutor , 206,52 


; Main Event Loop 


MAIN: 

CLR.L -CSP) SNIL for FilterProc 

PEA ItemHit ,VAR ItemHit 

—ModalDialog ;handle the dialog for us! 

MOVE ItemHit,Dd ;Get the result 

CMP *1,D0 ;,Is it Square Wave? 

BEQ Square ,Yes.... 

CMP 82 DO jIs it 4Tone? 

BEQ FourTone ,You got it.... 

CMP $3,D0 ;,Is it Bye Bye?? 

BEQ Adios jUh huh... 

BRA Main jKeep going till we get 
ja valid event... 

Square: 


MOVE.L ParamBlock,A® ;Get the Ptr to ioParamBlock 

MOVE.L fiSqEnd-SqBegin,36CA0) 
;The length of the data, so we 
,can tell the device manager 
;how much to write 


LEA SqBegin,A1 
MOVE.L A1,32CA0) 


;Ptr to our data buffer 


_Write ¿this is the actual Write call. 
;Be sure to have AQ pointing to 
your ioParamB lock! 

BRA Main We're done for now.. 

SqBegin: 

DCW -1 This tells the sound 


,driver that the data is 
,for the square-wave 
;driver. 


;Play the C major diatonic scale... 


DC.W 5937, 128,20 ;C 
DC.W 5278, 128,20 ;D 
DC.W — 4750, 128,20 
DC.W 4453, 128,20 
DC.W 3958, 128, 2 
DC.W 3562, 128, 20 
DC.W 3167, 128, 20 
DC.W 2969, 128, 20 
DC.W 3167, 128,20 
DC.W 3562, 128, 20 
DC.W 3958, 128,20 
DC.W — 4453, 128,20 
DC.W — 4750, 128, 20 
DC.W 5278, 128, 20 
DC.W 5937, 128, 20 
DC.  0,0,0 

SqEnd: DC.W Ø 


`% "-—. "e Ve 


we We Gs o0 


eo We We We Ve De . 
AaoomMmnNnoroanonwroaoa nm 


jEnd of the data 


FourTone: 


MOVE.L ParamBlock, Ad 
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;Get the Ptr to 


MOVE.L 86,36CA0) 


MOVE.L Wave, A2 


LEA FTSynthRec,A1 
MOVE.L #3,D8 
SetWave: 

MOVE.W #38, CA1) 


ADDA  834,A1 


MOVE.L A2, CA1)+ 
MOVE.L A2,(AD* 
MOVE.L A2,(A1)+ 
MOVE.L A2, CA1)+ 


jour ioParamBlock 


;ioCount Chow many 


;bytes to write) 


jin this case always 


36 bytes 


;Get the Ptr to the 
,waveshepe def 


;Get the Ptr to the sound table 


;Loop 4 times 


;Set the tone length 
to .5 seconds 

;, Adjust Al to point 
;to WavePtr fields 
jset ist WavePtr 
;Set 2nd WavePtr 
;Set 3rd WavePtr 
;Set 4th WavePtr 


DBRA — DO,SetWave 
LEA FTBegin, A3 


MOVE.L A3,32CA0) 


;Set the BuffPtr in 
;the PeramBlock 

,to point to our data 
;buffer 

;Set the FTSRecPtr 
jin the Data 

MOVE.L 3,03 ;Loop 4 times 

FTLoop: MOVE.LA2,2CA3) ;Set the 

;pointer to point 

;to the next sound 


LEA FTSynthRec, A2 


MOVE.L ParamBlock,A® ;Get Ptr to 
,ioPeremBlock in Ag 


-Write Write it! 

ADDA — 950,42 Point to the next 
; tone record 

DBRA 03,FTLoop jand loop... 

BRA Main ; Thank you... 


; The four-tone record is unique in that it is not actually 
;written to the sound driver. Rather, only a ptr to the 
,actual tones is written. This means that only one set of 4 
; tones can be written at a time. 


FTBegin: 
DC.W 1 ;Four tone = 1 
DC.L Ü ,Holder for Ptr to the actual 
; tones 
FTSynthRec 
DC.W 60 ;Do sound for 1 sec 


DC.L — $3CBB0,0 
DC.L — $58188,0 
DC.L — $408C3,0 
DC.L — $00000,0 
DC.L 8,9,9,8 ;Plece holders for 
;WevePtr's 


60 ;Do sound for 1 sec 
DC.L — $36485,0 
DC.L — $50F95,0 
DC.L — $60504,0 
DC.L $00000,0 
DC.L 8,0,0,0 ;Place holders for 
,WavePtr's 


DCW 75 

DC.L  $287CA,Ø 
DC.L  $3CB80,0 
DC.L  $39959,6 
DC.L $00000,0 
DC.L 0,0,0,0 


DCW 3B 


;.5 SEC 
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DC.L — $1E508,0 
DC.L $287CA, p 
DC.L $30959, 9 
DC.L $00000, 0 
DC.L 0,0,0,0 


ADIOS: LEA SaveRegs, Ad 
MOVE .L CAS), A6 
MOVE .L4CAQ),A7 
MOVEM.L (SP2*,D0-D7 /A9-A6 
RTS 
; Program Variables 
Sa DCB.L 2,8 ;For saving the SP etc.. 


DHandle: DC.L Ø ;For the dialog Handle 
ItesHit: DC.W Ø ;For _ModalDialog ParamBlock: 
DCL Ø ;For the ioPB 
Wave: DCL Ø ;For the WaveShape definition 
; Dialog Record 
DStorage: 0S.W DWindLen 


; *** Resource File eee 
; for Sound Exercize 81 


RESOURCE 'BDOG' Ø 'IDENTIFICATION' 
STRING_FORMAT 2 


DC.B 'FREEWAVE VER -8.1 OF 3/19/85' 
STRING_FORMAT Ø 


. ALIGN 2 

RESOURCE 'BNDL' 128 'BUNDLE' 

DC.L 'BDOG ' ,Neme of Signature 
DC.W 9,1 ;Data 

DC.L 'FREF ' ;FREF Mappings | 
DC.W Ü ; 1 Mapping € 1-12 8 ) 
DC.W 0, 128 

DC.L ‘TONS’ ; ICN® Mappings 

OC .W 0 ;2 Mappings € 1-12 8 ) 
DC.W 0, 128 

„ALIGN 2 

RESOURCE 'FREF' 128 ‘FREF#1' 

DC.B 'APPL',0,0,0 

„ALIGN 2 


RESOURCE 'ICN*' 128 ‘Application Icon' 
INCLUDE WaveIcon.ASM 


. ALIGN 2 
RESOURCE 'ICON' 128 'DlogIcon' 


INCLUDE SoundIcon.ASM 


; $** Dialog Box eee 
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„ALIGN 2 

RESOURCE 'DLOG' 128 'AboutBox' STRING_FORMAT 2 
DC.W 95,50,210,462 ;BoundsRect 

DC.W 1 ;ProcID 

DC.B 1,1 : TRUE for visible 

DC.B 0,0 ;FALSE for GoAway 

DC.L Ü ;Refcon (Chuckle! > 

DC.W 129 ;,UITL ResID 

DC.B 'HI' ;Title Cunused) 


,*** Dialog Box Items eee 


. ALIGN 

RESOURCE 'DITL' 129 'AboutBox items' 

DC.W 3 34 Items in the list 
3(4- 123) 

;* Item #1 © 

DC.L Ü ;Handle holder 


DC.W 114,41, 136,201 
DC.B 4 
DC.B ‘Square Wave ' 


;* Item #2 e 
DC.L ø 


;BoundsRect 
;Button 


;Text Preceded by length byte 


;,Handle holder 


DC.W 114,210, 136,361;BoundsRect DC.B 
4 


;Button 
DC.B ‘Four Tone ' ,lext Preceded by length byte 
;* Item *3 e 
DC.L ð ¿Handle holder 
DC. W 144,41, 166,361  ;BoundsRect 
DC.B 4 ; Button 
DC.B ‘Ive had enough fun for now' 


j Text Preceded by length byte 


je Item 84 e 
DC.L Ü 3 
DC.W 60, 194,92,226 
DC.B 128+32 


DC.B 2 
DC.W 128 
jEOF 


ISTART 


/Output Sound 


] 
SoundOf f 


/Resources 
SOResource 


/TYPE 'APPL' 'BDOG" 
$ 


;,Hendle Holder 
;BoundsRect 
;Disabled Icon 


; ICON ResID STRING.FORMAT Ø 


Linker File 
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Programmer's Forum 


Mondrian Shows Off Dissolve Effect 


DissBits: A subroutine to do "dissolve" shots 

One of the first sample Mac programs was Cary Clark's 
"File". The "About File" menu item did a nifty piece of 
animation with text which grew and seemed to "zoom out" 
toward the viewer. Clark calls this a “bit of fluff". I disagree: 
effects like this are part of the allure of the Mac. Here's a 
description of another visual effect which "File" inspired: a 
"dissolve" routine called DissBits, which fades from one image 
to another on the screen. 

The routine is patterned after Quickdraw's CopyBits, 
which copies a rectangle in one bitmap to any other rectangle 
in any other bitmap. Along the way, it can clip to any 
region, stretch the image if the rectangles aren't the same size, 
and use any transfer mode. DissBits performs only some of 
these functions: it will work with any two bitmaps, but the 
rectangles must be of the same size, no clipping is done, and 
the bits are always copied directly, as the "srcCopy" mode 
does. 

How does DissBits work? The idea is simple: pixels are 
copied from one rect to another in a random sequence which 
copies each pixel once. There are two tricky parts to this: 
finding a way to copy each bit only once and coding it to be 
fast. This article covers both issues. 

The random sequence which hits all the bits is simple to 
implement. Let's reduce it to a smaller problem first: 
Suppose we want to copy all bits in a rect H bits wide and V 
bits high. Then we want a sequence which produces all (v, h) 
combinations in the rect. Suppose instead we have a random 
sequence of numbers n, O through V*H. If we take each 
number n and compute h=(n / V) and v=(n mod V), that gives 
us all (v, h) pairs in the rect. So we've changed the problem 
of hitting every point to the problem of generating the first 
V*H integers in a random sequence. If we can find a "1- 
dimensional" sequence, that gives us the "2-dimensional" 
sequence. 

A way to generate the linear sequence without huge arrays 
is this: start with any number between 1 and N. To get the 
next sequence element, shift the number right by one bit. If a 
bit fell off in the shift, exclusive-or in a magic value (more on 
this value later). Repeat this to get more sequence elements. 
pus resulting sequence will be all the numbers from 1 through 
2k.1, where "k" depends on the magic value (don't worry, I 
really will explain about the magic values). To get numbers 
between 0 and N, choose a magic value such that 2k.1 is 
greater than or equal to N, and throw away elements which are 
too big. This may seem like a waste, but generating the extra 
elements is very fast. (Note: the sequence doesn't produce the 
value zero; this has to be done with special-case code.) 

An example: if you want to cover an 80-by-100 bit rect, 
you must produce the numbers 0 through 7999 and map those 
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Mike Morton 
Cambridge, MA 


Mondrian Game 


R simple demonstration of the "dissBits" dissolve effect. 
To invert a rectangle, click anywhere outside the menu bar. 
Drag until you have the rectangle you want, then release. 


The dissolve subroutine is public domain “freeware”. 


Mike Morton 
Version 2.0, September 1985 
(click to continue) 


to the points in the rect. To do this, use a magic value of 
$1D00, which will produce a sequence from 1 through 213-1; 
discard all the ones above 7999. Add special-case code to 
throw in the value 0. 

How does one know which magic value to use? If you're 
into abstract algebra, you'll know that the magic values are 
related to prime polynomials. If you'd rather take the 
empirical approach, you can write a program to find the 
values. This took two weeks of CPU time on a Lisa. You'll 
probably want to use the table in the DissBits source. It gives 
the magic values to use for all "k"s from 2 to 32. (Be careful: 
the table is compressed; see the code which expands it.) 

To sum up the sequence problem: to copy the pixels of 
one rect to another requires these steps: Find the total number 
of pixels in the rect. Find "k" which will produce a sequence 
including that number of elements (and a few more, which 
will be discarded). Cycle once through the sequence, taking 
each element and checking if it's in range. If so, map the 
integer to coordinates inside the rect and copy that point. 
When the sequence returns to the first element ( it always 
will), copy the point (0, 0), which the sequence doesn't 
produce. 

The actual implementation has one difference: instead of 
using "modulo" and division to map a sequence element to 
two coordinates, the number is broken bit-wise, extracting the 
low bits to get one coordinate, and the high bits to get the 
other. This means that the sequence is slightly longer, and 
that both coordinates must be checked to see if they're in 
range, but the time saved by avoiding a 68000 DIV instruction 
is worth it. 

Now for the graphics part. To copy a pixel from one rect 
to another, we want to know the state of the source pixel. We 
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could use Quickdraw's "GetPixel", and 
then plot a black or white pixel 
depending on the source pixel. This 
would be too slow. Instead, DissBits 
works directly with the graphical data. 

All graphics work is done using 
bitmaps: arrays of pixels in memory. 
A bitmap has a "base address", which 
points to the data. It has a "bounds" 
rect, which describes the coordinate 
system of the bitmap: the range of v 
and h coordinates. And it has a field 
called "rowbytes", which describes how 
many bytes are used to store each row 
of graphical data. The "rowbytes" field 
is important to move "down" one 
pixel in the bitmap, you skip "ahead" 
by one row of bytes in memory — 
"rowbytes" tells you how much to 
Skip. 

The link between a coordinate pair 
(v,h) and a bit in memory is through a 
bitmap. The point is (v-bounds.top) 
rows down into the bitmap and (h- 
bounds.left) columns across into it. 
Call these offsets "dv" and "dh". The 
base address of the bitmap is where you 
start. Then to skip "dv" rows, each of 
"rowbytes" bytes, skip (dv*rowbytes) 
bytes. The address of the start of the 
row Is: 

baseaddr + dv*rowbytes 

To index by "dh" bits into the 
row, remember that each byte is eight 
bits. To get to the correct byte, the 
above address needs (dh/8) more bytes, 
so the final byte address is: 

pixaddr = baseaddr + dv*rowbytes 
+ (dh/8) 

To select the correct bit number 
within this byte, use the remainder 
from computing (dh/8) — this is (dh 
mod 8). Unfortunately, the 68000's 
method of bit numbering is backwards 
from the way Quickdraw numbers bits, 
so the 68000 bit number in the byte is: 

pixbit = 7 - (dh mod 8) 

These formulas let us take a point 
(v, h) in a bitmap and find the bit in 
memory, sO we can quickly test the 
point with the instruction 

BTST pixbit, pixaddr 

If we also find bit and byte 
addresses for the pixel we want to copy 
to, we can branch after the BTST and 
do either a BSET or BCLR to set the 
destination pixel to match the source. 


program Mondrian; 


( Mondrian -- a demo of the "dissBits" procedure. The user clicks 
and drags; the selected rectangle is inverted by copying the rect 
from the screen to an offscreen bitmap using the "srcXor" mode 
of copyBits, then dissolving that to the screen, giving the 
impression of slowly inverting in place. ) 


( Written by Mike Morton for MacTutor ) 
( Converted to TML Pascal by David E. Smith ) 


($I Mentypes.IPes ) ( TML Mac libreries) 
($I QuickDraw. IPas ) 

($1 OSIntf.IPas ) 

($1 ToolIntf . IPAS ) 


const 
appleMenu = 1; 
aboutI tem = 1; ( menu item: About Mondrian... } 
f ileMenu = 2; 
quitItem = 1; ( menu item: Quit ) 
lastMenu = 2; ( number of menus ) 
mBarHe ight = 22; { height of the menu bar, in pixels } 
applesymbol - 20; (apple symbol character j 
var 
myPort: grafPort; ( our graphics environment ) 
bits: bitmap; ( the offscreen bitmap ) 
done: boolean; ( flag for the main loop ) 
myMenus: array[1..lastMenu] of menuHandle; ( for the menu manager ) 
ev: eventrecord; ( for main loop, or awaiting click ) 


procedure dissbits (sb, db: bitmap; sr, dr: rect); external; ( dissolver ) 


( Frame a rectangle, even it "topLeft" and "botRight" are oriented wrong. ) 


procedure frameNeatRect (VAR r: rect); ( draw rect; flip corners if needed ) 
var 

rc: rect; ( copy of rect (don't change caller's) ) 
begin; 

pt2rect (r.topLeft, r.botRight, rc); ( sort out the rectangle's 

corners ) 
frameRect (rc); ( now draw it } 
; ( procedure frameNeatRect ) 


( Get the mouse location, but don't let them drag into the menu bar. ) 


pore getScrMouse (VAR p: point); ( get mouse loc, avoiding the menu ber ) 
begin; 


getMouse (p); ( get mouse location in global coords ) 
if p.v « mBarHeight ( in the menu ber? ) 

then p.v := mBarHeight; ( yes: force it to below the bar ) 

; ( procedure getScrMouse ) 


( Called for a click on the "desk". Track the mouse, sampling slowly to 
avoid shimmer. When they release, dissolve and invert the selected area. ) 


procedure doinvert; ( track mouse; invert the rect ) 
var | 
alarm: longint; ( tine et which we should sample mouse ) 
r: rect; ( rectangle the user selected ) 
mloc: point; ( mouse location ) 
n, 
penMode (patXor); ( so we can easily undraw the rect ) 
getScrMouse (r.topLef t); ( remember where we started ) 
r.botRight := r.topLeft; ( initially, the rectangle is null ) 
while button do ( wait for the button to be up ) 
begin; 
alarm := tickcount * 3; ( what time should we wake up? ) 
repeat until tickcount >= alarm; ( delay a bit Cavoid flicker) ) 
getScrMouse (mloc); ( where's the mouse now? } 
if not equalPt (mloc, r.botRight) ( did it move from where it was last? ) 
then begin; ( yes! they've done some dragging ) 
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fremeNeatRect (r); 
r.botRight := mloc; 


( erase rect (we're XORing, remember?) ) 
( remember the new location ) 


Putting all this together, we can 
take two rectangles of equal size, each 


frameNeatRect (r); ( and drew the new rectangle ) 
end; ( of changing rectangles ) 


in a bitmap, and produce a sequence of 
end; ( of looping while the button is down ) 


integers which (discarding some 
elements) takes us through all 
coordinate pairs in the rect. For each 
point, we use the bitmaps to find the 
actual bits in memory, test the source 
bit and set the destination bit 


fremeNeatRect (r); ( button's up: erase lest rectangle ) 
pt2Rect (r.topLeft, r.botRight, r2; ( streighten things out for our caller ) 
copyBits (screenbits, bits, r, r ,notsrcCopy,nil); que & flip ) 
dissbits (bits ,screenbits, r, r); t "fede to black" Cor whatever) ) 


3 


procedure about; ( blather about the program } appropriately. 
const M : : x 
ost of the algorithm is described 
textHeight = 22; ixel height for a row of text : 
ver 3 (P 3 } in the code. The code has become 


oldbits: bitmap; 
aboutr: rect; 
say (s: str255); 


( for saving the screen's bitmap ) 
{ general purpose rect 
( print a string; move text rect down } 


Obscure as successive optimizations 
have been added. One very important 
optimization should be explained in 
detail: a lot of the time spent in the 
loop is calculating (dv*rowbytes). If 
"rowbytes" is a power of two (as it is 
for the Mac screen), DissBits notices 
this and shifts into "middle gear" using 
a different loop and using shifts to avoid 
the multiply. If the rects being copied 
are the full width of the bitmaps, some 
more tricks can be done, and a third 


"n 

textbox(ptr Clongint(@s)+1), length (s), aboutr, ( print the text... ) 
teJustCenter ); ...Centered ) 

offsetRect Caboutr, Ø, textHeight); ( slide down one line ) 


d 
begin; ( main code for "about" } 
oldbits := screenBits; ( remember old bitmap (the screen) ) 
setPortBits (bits); ( draw offscreen ) 
eboutr := screenBits. bounds; ( start with the whole screen } 
eraseRect Caboutr); ( clean the whole (offscreen ) 


penNormal; 
insetRect Caboutr, 30, 30); 
fremeRect Caboutr); 


( no funny stuff with the pen here ) 
( move ina bit ) 
( outline the rectangle ) 


insetRect Caboutr, 2, 2); 
frameRect Caboutr); 
insetRect Caboutr, 2, 2); 


{ move in a teeny bit more } 


( outline another rect 


loop is used. At top speed, DissBits 
can copy an image onto the full screen 
in under 3.5 seconds. 


( move in another teeny bit more ) 
( outline the last rectangle ) Low Level Tricks 
( keep "textBox" rects small ) Most of the 


fremeRect Caboutr); 
insetRect Caboutr, 1, 1); high-level 
optimizations are too detailed to cover 


eboutr.top := aboutr.top + 48; ( start text a ways down the screen ) 
here; the comments describe them in 


eboutr.bottom :- aboutr.top + textHeight; ( make the rect one line high ) 
il. me low- i 

textFont (8); ( write in the system font ) er ae x ow-level tricks worth 

textSize (12); ( end keep it legible ) spartans aie: 

say C'A simple demonstration of the "dissBits" dissolve effect. '); * When changing Quickdraw's 

say ('To invert a rectangle, click anywhere outside the menu bar.'); numbering of bits to the 68000 

say (Drag until you have the rectangle you went, then release.'); conventions, it's actually not 


say (''); ( skip a line } 
say (‘The dissolve subroutine is public domain "freeware".'); necessary to map x to (7-x). Since 
only the low 3 bits of the bit index 


say C7); ( skip a line ) 
say (Mike Morton’); are used in bit instructions, a NOT 


say ('Version 2.0, September 1985'); 


say C (click to continue)'); ( don't hide the mode ) will convert the bit offset. (See the 
eboutr := screenBits.bounds; ( again, specify the whole screen ) code after LOOPROW.) 
dissBits (bits, oldbits, aboutr, aboutr); ( dissolve in offscreen text ) * The first part of getting a new 


repeat until getnextevent(mdownmask*keyDownMask, ev); 
setPortBits Coldbits); 
eraseRect (screenbits bounds); 


( await click ) 
( go back to drawing on the screen ) 
clean everything up ) 


sequence element is shifting it to the 
right. If no magic value needs to be 


drawMenuBar ; ( end bring back the menu bar ) XOR-ed in, then the row number (in 
; ( procedure about ) the high bits of the sequence element) 
procedure docommand (cmd: longint); ( do a menu command ) is in range. (See the code after 
ver 


NEXT. 
menu, item: integer; { menu number, item number for menu } « If the D. sequence element is the 
begin; 


menu := hiword (cmd); ( extract menu number... ) magic value, the next to last element 
item := sonore (cmd); $ ond ise ae ) before the cycle loops is one (this is 
case menu o ranch on the selected menu . : 
eppleMenu: about; ( this is our only apple-menu item ) casy to prove). When 1 is shifted 
fileMenu: done := true; ( assume they hit "Quit"; flag it ) right, it becomes 0, so the end of the 
end; ( of case on meny ) sequence is easy to detect. (See the 
hilitemenu (0); ( un-highlight the menu ) code after NEXT.) 
e Since the code to find the next 


é 
( handle a mouseclick ) sequence element wants to detect the 


procedure click Cev: eventrecord); 
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case where no carry has occurred, and ver 


es . code: integer; { type of click } 
nu tod iue pou is m E beni windowP tr ; ( dummy for findwindow call ) 
W W n; 
BHI instruction. code := findwindow Cev.where, ino ( look up the window ) 
2 ; ; cese code of brench on what happened: 
When the high bits of the Sequence inmenubar: docommand (menuselect Cev.where)) ; ( menu: do a menu command ) 
element are shifted down to get the indesk: doinvert; ( desk: track the mouse; dissolve ) 
row number, they're soon multiplied end; ( of branching on code $ 
by the "rowbytes" value. If end; ( procedure click ) 
“rowbytes" is even, it can be halved procedure eventhendle; — ( main loop's routine ) 
and the shift-down can be reduced by begin; 
one. The code in HALFLOOP does if getnextevent Ceveryevent, ev) ( was there an event? ) 
: ias bp then begin; ( yes: handle it ) 
this repeatedly, until "rowbytes" is case ev.what of ( brench on the type ) 
odd. mousedown: click Cev); ( handle a click ) 
* In the fastest case (copying the whole Pe al autokey: sysbeep (2) ; T ore x ) 
screen), it doesn't matter if the bit- end; ( of handling an event ) 
numbering is reversed or not, since end; ( procedure eventhandle ) 
every bit will be copied anyway. TS — 
This step is skipped in the "high- procedia init; ( initialize everything ) 
gear" loop. i: integer; ( menu counter ) 
The Mondrian Demo n, 
* Noida initGref CéthePort); ( fire up quickdraw ) 
Mondrian X short demo program openPortCémyPort); ( get & drewing environment ) 
for the dissolve effect is given here. Be initFonts; ( we use the font manager for "about" ) 
sure to pull out "About Mondrian" from ial ; eee ( end this E locating mouseclicks ) 
: ; e menu manager 
a apple ced see the high-speed, eraseRect (myPort.portRect); ( clean the screen ) 
ull-screen dissolve. 
DissBits is a good example of how RB Fedora ( loop iliac ell bs n) o) 
: : ; = u ; ...8nd read in each one 
the Mac's processing power can animate nyMenus [app leMenu ^^ .menudeta[ 1] := chrCapplesymbol); ( "e" -> apple ) 
an effect which few other for i := 1 to lastMenu do ( again, loop through menus... ) 
microcomputers can do in real time. inser tMenu (nyMenus [i], 0); ( ...ünd now install each one ) 
Even machines with faster 68000 drawMenuBar ; ( show the completed menu bar ) 
processors, such as the Amiga, can't get done := false; ( tell main loop program's not done ) 
the speed the Macintosh can in copying initCursor ; ( set the arrow cursor -- we're ready ) 
the full screen, because of Apple's end; ( procedure init ) 
decision to make the screen's width a procedure initoffs (VAR bits: bitmap); ( set up the offscreen bitmap ) 
power of two pixels, allowing shifts var in babet ihe itaso) 
: T rows: integer; number of rows in the bitmap 
instead of multiplies. ] cols: integer; ( number of columns ) 
l a sos Is a ow d e To outen integer; ( number of bytes needed for bitmap ) 
mine. 1 use it in nearly everything m — 
write. I hope you'll use it in your E do ( lots of operations on the bitmap: ) 
applications, and perhaps be inspired to bounds := screenbi ts bounds; ( copy the screen's coordinates ) 
exploit the Mac's visual technology in A. = Sauber a cs eat ( da " of rows in the screen.. yl 
: (e th: cols := bounds.right-bounds. left; ...8nd the number of columns 
Hips d D. as Cary Clark's "bit of ( Note that a bitmap's "rowbytes" must be even; hence this odd formula: ) 
uff" brought about DissBits. rowbytes := (((cols)*15) div 16) * 2; — ( compute number of bytes per row ) 
Putting It All Together totbytes := rowbytes * rows; ( rows*(bytes/row) = bytes for bitmap ) 
by re := qdptr (newptr Ctotbytes));  ( allocate space for the bitmap ) 
end; 
David E. Smith 
Now comes the problem of putting i maine Sette pasenaa:? =ø | ( allocation failed? ) 
all the pieces together. The Pascal eon ib ( yes: bag it before we crash ) 
. ° é P] 
source code for Mondrian was written DrawString C'Sorry! Not enough memory for Mondrian to run... click to exit’); 
first in Lisa Pascal and has been f lushEvents Ceveryevent, 0); ( don't allow "clickahead" ) 
converted here to TML Pascal on the Bere ee en nee, ( weit DE Erud 
Macintosh. Actually, very little was end; ( of handling failed memory allocation ) 
required to make this conversion; only end; ( procedure initoffs ) 
the TML libraries were substituted for ( main prograa ) 


the Lisa compiler versions. Nearly all 
the source code compiled without begin; 


init; ( initialize Macapplication things ) 
change. The TML product has been initoffs (bits); ( create an offscreenbitmap ) 
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flushEvents Ceveryevent, 9); 


repeat eventhandle 
until done; 


( ignore old clicks, keys, etc. ) 


( do the user's bidding...) 
.'til they get bored and ask us to stop ) 
( program Mondrian ) 


Resource File (MDS) 


Mondr ian_rscs.asm 
resource file for the Mondrian game 
created using the assembler 
signiture is creator tag 


AI - we We We De 


ESOURCE 'MDRN' Ø ‘IDENTIFICATION’ 


DC.B 42, ‘Mondrian version 
2.8 -- 21 September 1985' 
„ALIGN 2 
RESOURCE 'BNDL' 128 'BUNDLE' 
DC.L 'MDRN' 
DC.W 0,1 
DC.L ' ION ' 
DCW Ø ;* Maps-1 
DC.W Ø, 128 ;MAP Ø TO 128 
DC.L 'FREF ' ;FREF 
DCW Ø ;* of maps-1 
DC.W 0,128 ;MAP 9 TO 


RESOURCE 'FREF' 128 'FREF 1' 
DC.B 'APPL', Ø, Ø, Ø 


„ALIGN 2 
RESOURCE 'ICN"' 128 ‘MY ICON' 


; FIRST APPLICATION ICON BIT MAP 


DC.L $00010000, $00028000, $00044000, 
$00082000 
DC.L $09101000, $002FF800, $004FF400, 
$008FF200 


DC.L $010FF100, $020FF080, $040tOF40, 


$080E0F 20 


DC.L $13EEGF 10, $2221FF08, $4221FF04, 


$8221C082 


DC.L $42218041, $22213022, $13E1C814, 


$28 1E 7F ØF 


DC.L $04023007, $02010007, $Ø 1Ø 18097, 


$208 1E007 


DC.L $005ESFE7, $003ESEIF, $001ESCOT, 


$0009F 800 


DC.L $0005F000, $00022000, $00014000, 


$00008000 


; mask data: 32 rows of 32 bits 


DC.L $00010000, $00038000, $0001C000, 
000 


$000FE 


DC.L $001FFO00, $003FF800, $00TFFCOD, 
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$00FFFEOQ 

DC.L $O1FFFFO®, $O3FFFF80, $OTFFFFCO, 
$0FFFFFEO 

DC.L $iFFFFFF0, $3FFFFFF8, $7FFFFFFC, 
$FFFFFFFE 

DC.L $7FFFFFFF, $3FFFFFFE, $IFFFFFFC, 
$0FFFFFFF 

DC.L $O7FFFFFF, $03FFFFFF, $O1FFFFFF, 
$00FFFFFF 

DC.L $OO7FFFFF, $003FFE1F, $001FFCO7, 
$000FF8900 

DC.L $eo07F000, $0003E000, $0001C000, 
$00008000 


; MENU BAR RESOURCES 


. ALIGN 2 
RESOURCE 'MENU' 1 'epple menu' 


DC.W 1 ,MENU ID 
DC.W Ø ; WIDTH HOLDER 
DC.W Ø ; HEIGHT HOLD 
DC.L Ø RESOURCE ID 
DC.L $1FF jENABLE ALL 
DC.B 1 ; TITLE LENGTH 
DC.B 20 ; APPLE title 
DC.B 18 ; ITEM LENGTH 
DC.B ‘About Mondrian... ' 
DC.B 0 ; NO ICON 
DC.B Ø ; NO KEYBOARD 
DC.B Ø ; MARKING 
DC.B Ø ; STYLE OF TEXT 
DC.B 0 ; END OF MENU 

„ALIGN 2 

RESOURCE 'MENU' 2 'file menu' 
DC.W 2 ,MENU ID 
DC.W 0 ; WIDTH HOLDER 
DC.W Ø ;HEIGHT 
DC.L Ø ;RESOURCE ID 
DC.L $iFF ;ENABLE ALL 
DC.B 4 ; TITLE LENGTH 
DC.B 'File'; file nenu 
DC.B 4 ; ITEM LENGTH 
DC.B ‘Quit’ 
DC.B Ø ; NO ICON 
DC.B Ø ; NO KEYBOARD 
DC.B Ø ; NO MARKING 
DC.B 8 ; STYLE OF TEXT 
DC.B Ø ; END OF MENU 


covered extensively by Alan Wootton in 
the Pascal column and is highly 
recommended as an inexpensive full- 
blown Pascal compiler that is MDS 
"REL" file compatible. This source 
code is compiled to MDS assembly 
source as shown graphically in figure 3. 
That assembly code is then run through 
the MDS assembler to produce the 
"REL" file for the MDS linker. In this 
respect, the product works much like the 
Absoft Fortran package, only better 
because there is no "run time" package 
to fool around with and no 
incompatibility problems with MDS as 
we have noted in our Fortran columns. 
[MICROSOFT please take note!!] Only 
one problem was encountered. It seems 
TML does not handle the Writeln 
Statement yet. That was replaced with 
DrawString, which worked fine. 

Even though the TML Pascal 
produces an MDS link file for you, it is 
best to either edit that file or use your 
own. In this case, I used my own, 
shown below. The DissBits subroutine 
[see next article] is assembled and linked 
with the Mondrian source and the 
resource file. As is my custom, I chose 
to do the resources in assembly so they 
could be assembled with MDS and 
linked directly to the two ".REL" files, 
thus avoiding the RMaker loop. One 
thing to note in the link file produced 
by the TML compiler is the names of 
the Pascal support routines that must be 
linked to your source code also. The 
result is a stand-alone, fully machine 
code program! 


Linker File 


IPAS$Xfer 
] 


) 
/OUTPUT Mondrian Game 


mondr ian 
dissbits 
PAS$Sys 
OSTraps 
ToolTraps 


/TYPE 'APPL'- 'MDRN' 

/BUNDLE 

/RESOURCES 
MONDRIAN_RSCS ae 


Pd 


$ TAN 
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